From 9405a04c1341861d05ced4f430a0a5b8a99c6c0e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 7 Jul 2026 20:05:10 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20align=20sync=20API=20docs=20with?= =?UTF-8?q?=20owner=20packages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/build-logger.md | 3 +++ docs/api/config-error.md | 11 ++++---- ...ured-logger-file-default-policy-or-none.md | 3 +++ .../configured-logger-file-default-policy.md | 3 +++ docs/api/configured-logger-file-policy.md | 3 +++ .../configured-logger-file-rotation-config.md | 3 +++ ...onfigured-logger-file-rotation-failures.md | 13 +++++---- .../configured-logger-file-runtime-state.md | 3 +++ docs/api/configured-logger-file-set-policy.md | 3 +++ .../configured-logger-file-set-rotation.md | 3 +++ docs/api/configured-logger-file-state.md | 3 +++ docs/api/file-rotation-config-to-json.md | 3 ++- docs/api/file-rotation-type.md | 12 +++++---- docs/api/file-sink-policy-to-json.md | 3 ++- docs/api/file-sink-policy.md | 11 ++++---- docs/api/file-sink-rotation-failures.md | 14 ++++++---- docs/api/file-sink-state-to-json.md | 3 ++- docs/api/file-sink-state.md | 12 +++++---- docs/api/file-sink-type.md | 27 +++++-------------- docs/api/file-sink.md | 4 ++- docs/api/file.md | 6 ++++- docs/api/logger-config-type.md | 11 ++++---- docs/api/parse-and-build-logger.md | 3 +++ docs/api/parse-logger-config-text.md | 3 +++ docs/api/queue-config-type.md | 11 ++++---- docs/api/queue-overflow-policy.md | 5 ++-- docs/api/queued-sink-type.md | 1 + docs/api/runtime-file-state-to-json.md | 3 ++- docs/api/runtime-file-state.md | 11 ++++---- ...untime-sink-file-default-policy-or-none.md | 3 +++ docs/api/runtime-sink-file-default-policy.md | 3 +++ docs/api/runtime-sink-file-policy.md | 3 +++ docs/api/runtime-sink-file-rotation-config.md | 3 +++ .../runtime-sink-file-rotation-failures.md | 13 +++++---- docs/api/runtime-sink-file-runtime-state.md | 3 +++ docs/api/runtime-sink-file-set-policy.md | 3 +++ docs/api/runtime-sink-file-set-rotation.md | 3 +++ docs/api/runtime-sink-file-state.md | 3 +++ docs/api/sink-config-type.md | 11 ++++---- docs/api/sink-kind.md | 11 ++++---- docs/api/stringify-file-sink-policy.md | 3 ++- docs/api/stringify-file-sink-state.md | 3 ++- docs/api/stringify-runtime-file-state.md | 3 ++- docs/api/text-formatter-config-type.md | 11 ++++---- docs/api/with-file-rotation-i64.md | 4 ++- docs/api/with-file-rotation.md | 4 ++- 46 files changed, 183 insertions(+), 98 deletions(-) diff --git a/docs/api/build-logger.md b/docs/api/build-logger.md index f371518..bc4a210 100644 --- a/docs/api/build-logger.md +++ b/docs/api/build-logger.md @@ -15,6 +15,8 @@ key-word: Build a `ConfiguredLogger` from `LoggerConfig`. This is the main config-to-runtime bridge for synchronous logging and is the builder used before async wrapping in config-driven async flows. +At the public `src` layer, this API is the entry facade that consumes the shared config model owned by `src/config_model` and produces a `ConfiguredLogger` backed by `src/runtime.RuntimeSink`. + ### Interface ```moonbit @@ -34,6 +36,7 @@ pub fn build_logger(config : LoggerConfig) -> ConfiguredLogger {} Detailed rules explaining key parameters and behaviors - `build_logger(...)` first constructs a base `RuntimeSink` from `config.sink`, then applies `config.queue` when present, and finally builds `Logger::new(...)` with `config.min_level`, `config.target`, and `config.timestamp`. +- The returned file-control and file-diagnostics helpers are still facade methods over `RuntimeSink`, which in turn delegates file behavior to `src/file_runtime` and file model values to `src/file_model`. - The returned logger still supports normal logging methods because `ConfiguredLogger` is `Logger[RuntimeSink]`. - The returned logger also keeps inherited logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - That means `log(..., target=...)` can override the target for one write, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`. diff --git a/docs/api/config-error.md b/docs/api/config-error.md index d424f1d..5c7dab5 100644 --- a/docs/api/config-error.md +++ b/docs/api/config-error.md @@ -2,8 +2,8 @@ name: config-error group: api category: config -update-time: 20260613 -description: Public config parsing error alias used by synchronous config-loading helpers. +update-time: 20260707 +description: Public config parsing error re-exported from config_model for synchronous config-loading helpers. key-word: - config - error @@ -13,12 +13,12 @@ key-word: ## Config-error -`ConfigError` is the public error type raised by synchronous config parsing helpers. It is a direct alias to the internal config error definition and currently exposes a single structured error case for invalid input. +`ConfigError` is the public error type raised by synchronous config parsing helpers. On the root `src` facade, it is re-exported from `src/config_model`, which is the real owner of the structured config error definition. ### Interface ```moonbit -pub type ConfigError = @utils.ConfigError +pub using @config_model { type ConfigError } ``` #### output @@ -29,7 +29,8 @@ pub type ConfigError = @utils.ConfigError Detailed rules explaining key parameters and behaviors -- This is a type alias, not a separate public wrapper. +- This root surface is a re-export, not the concrete owner definition. +- The concrete error lives in `@config_model.ConfigError`, not in `@utils`. - The current public error case is `ConfigError::InvalidConfig(message)`. - The alias is used by parsing helpers such as `parse_logger_config_text(...)` and by lower-level config parsing routines beneath it. - Error messages describe concrete schema problems such as invalid JSON, wrong value types, unsupported enum text, or missing required values for a chosen sink kind. diff --git a/docs/api/configured-logger-file-default-policy-or-none.md b/docs/api/configured-logger-file-default-policy-or-none.md index 8acfb76..1919a48 100644 --- a/docs/api/configured-logger-file-default-policy-or-none.md +++ b/docs/api/configured-logger-file-default-policy-or-none.md @@ -15,6 +15,8 @@ key-word: Read the default runtime file policy from a `ConfiguredLogger` only when it is actually file-backed. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and avoids fabricating that model on non-file variants. + 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 @@ -37,6 +39,7 @@ 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)`. +- The wrapped value is the shared `@file_model.FileSinkPolicy` model, not a configured-logger-owned concrete type. - Non-file sinks return `None`. - This helper is useful when callers need to compare runtime drift or restore defaults without fabricating file semantics. diff --git a/docs/api/configured-logger-file-default-policy.md b/docs/api/configured-logger-file-default-policy.md index 0001b06..560e037 100644 --- a/docs/api/configured-logger-file-default-policy.md +++ b/docs/api/configured-logger-file-default-policy.md @@ -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. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates default-policy reads to the wrapped `RuntimeSink`. + `file_default_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_default_policy_or_none()`. ### Interface @@ -37,6 +39,7 @@ 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. +- The returned policy object itself is the shared `@file_model.FileSinkPolicy` model, not a configured-logger-owned concrete type. - 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()`. diff --git a/docs/api/configured-logger-file-policy.md b/docs/api/configured-logger-file-policy.md index fd357ca..f0eaa14 100644 --- a/docs/api/configured-logger-file-policy.md +++ b/docs/api/configured-logger-file-policy.md @@ -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. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates policy reads to the wrapped `RuntimeSink`, which in turn reaches file-backed variants that ultimately use `src/file_runtime.FileSink`. + `file_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_policy_or_none()`. ### Interface @@ -37,6 +39,7 @@ 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. +- The returned policy object itself is the shared `@file_model.FileSinkPolicy` model, not a configured-logger-owned concrete type. - 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()`. diff --git a/docs/api/configured-logger-file-rotation-config.md b/docs/api/configured-logger-file-rotation-config.md index 61833c4..0866553 100644 --- a/docs/api/configured-logger-file-rotation-config.md +++ b/docs/api/configured-logger-file-rotation-config.md @@ -15,6 +15,8 @@ key-word: Read the current rotation configuration used by a `ConfiguredLogger` file sink. This helper exposes the active runtime rotation parameters when rotation is enabled. +The returned `FileRotation` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates rotation reads to the wrapped `RuntimeSink`. + ### Interface ```moonbit @@ -35,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks return their current rotation configuration when enabled through the wrapped `RuntimeSink`. - Queued file sinks forward the config from the wrapped inner file sink. +- The returned rotation object itself is the shared `@file_model.FileRotation` model, not a configured-logger-owned concrete type. - Non-file sinks return `None`. - This helper is useful when callers need active runtime rotation parameters rather than only a boolean flag. diff --git a/docs/api/configured-logger-file-rotation-failures.md b/docs/api/configured-logger-file-rotation-failures.md index b250345..a3398a2 100644 --- a/docs/api/configured-logger-file-rotation-failures.md +++ b/docs/api/configured-logger-file-rotation-failures.md @@ -2,7 +2,7 @@ name: configured-logger-file-rotation-failures group: api category: runtime -update-time: 20260512 +update-time: 20260707 description: Read the number of rotation failures recorded by the configured runtime file sink. key-word: - logger @@ -13,7 +13,7 @@ key-word: ## Configured-logger-file-rotation-failures -Read the number of rotation failures recorded by a `ConfiguredLogger` file sink. This helper is useful when runtime rotation behavior should be observed operationally. +Read the number of runtime file-rotation attempts whose critical file steps failed in a `ConfiguredLogger`. ### Interface @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks report their recorded rotation-failure count through the wrapped `RuntimeSink`. - Queued file sinks forward the metric from the wrapped inner file sink. - Non-file sinks return `0`. +- For file-backed paths, the counter covers incomplete rotations caused by critical remove/rename/reopen failures, not every possible file-health issue. - The counter is cumulative until reset. ### How to Use @@ -49,7 +50,7 @@ When support output should reveal whether rotation is failing: let count = logger.file_rotation_failures() ``` -In this example, the configured logger exposes a focused metric for rotation-path health. +In this example, the configured logger exposes whether runtime file rotation stopped completing its critical steps. #### When Validate Runtime Rotation Tuning @@ -58,7 +59,7 @@ When changed rotation settings should be checked in operation: ignore(logger.file_rotation_failures()) ``` -In this example, callers can observe whether runtime rotation changes introduced problems. +In this example, callers can observe whether runtime rotation changes introduced incomplete rotations. ### Error Case @@ -67,8 +68,10 @@ e.g.: - If callers need both rotation config and failure metrics, they should combine this helper with `file_rotation_config()` or `file_state()`. +- This counter does not identify the exact remove/rename/reopen step that failed. + ### Notes -1. Use this helper when diagnosing file rotation reliability. +1. Use this helper when diagnosing incomplete file rotations. 2. It is especially relevant when runtime rotation policy can change after startup. diff --git a/docs/api/configured-logger-file-runtime-state.md b/docs/api/configured-logger-file-runtime-state.md index fb90248..c279031 100644 --- a/docs/api/configured-logger-file-runtime-state.md +++ b/docs/api/configured-logger-file-runtime-state.md @@ -15,6 +15,8 @@ key-word: Read combined file and queue runtime state from a `ConfiguredLogger`. This helper is the richest file-specific diagnostics API on config-built runtime loggers. +The returned `RuntimeFileState` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates runtime file-state reads to the wrapped `RuntimeSink`. + ### Interface ```moonbit @@ -35,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks return `Some(RuntimeFileState)` through the wrapped `RuntimeSink`. - Queued file sinks include both file status and queue metrics in the returned state. +- The returned snapshot object itself is the shared `@file_model.RuntimeFileState` model, not a configured-logger-owned concrete type. - Non-file sinks return `None`. - This helper is richer than `file_state()` because it can also surface queued backlog and dropped counts. diff --git a/docs/api/configured-logger-file-set-policy.md b/docs/api/configured-logger-file-set-policy.md index dbd5809..3d66629 100644 --- a/docs/api/configured-logger-file-set-policy.md +++ b/docs/api/configured-logger-file-set-policy.md @@ -15,6 +15,8 @@ key-word: Apply a bundled runtime file policy update to a `ConfiguredLogger`. This helper updates append mode, auto-flush, and rotation together through one runtime policy object. +The input `FileSinkPolicy` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates policy mutation to the wrapped `RuntimeSink`. + ### Interface ```moonbit @@ -36,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks update append, auto-flush, and rotation together through the wrapped `RuntimeSink`. - Queued file sinks forward the policy update to the wrapped inner file sink only when no queued records are pending. +- The accepted policy object itself is the shared `@file_model.FileSinkPolicy` model, not a configured-logger-owned concrete type. - Non-file sinks return `false`. - This helper is broader than the single-setting setters because it updates the whole file policy in one call. - If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different policy bundle than the one they were queued under. diff --git a/docs/api/configured-logger-file-set-rotation.md b/docs/api/configured-logger-file-set-rotation.md index 4dc6506..0557d02 100644 --- a/docs/api/configured-logger-file-set-rotation.md +++ b/docs/api/configured-logger-file-set-rotation.md @@ -15,6 +15,8 @@ key-word: Update the rotation policy used by a `ConfiguredLogger` file sink. +The input `FileRotation` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates rotation mutation to the wrapped `RuntimeSink`. + ### Interface ```moonbit @@ -36,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks update their runtime rotation policy through the wrapped `RuntimeSink`. - Queued file sinks forward the update to the wrapped inner file sink only when no queued records are pending. +- The accepted rotation object itself is the shared `@file_model.FileRotation` model, not a configured-logger-owned concrete type. - Non-file sinks return `false`. - This helper changes policy only; it does not itself rotate or flush pending data. - If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different rotation policy than the one they were queued under. diff --git a/docs/api/configured-logger-file-state.md b/docs/api/configured-logger-file-state.md index ab6c112..1ca7e45 100644 --- a/docs/api/configured-logger-file-state.md +++ b/docs/api/configured-logger-file-state.md @@ -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. +The returned `FileSinkState` value is owned by `src/file_model`; this configured-logger surface is a facade over `Logger[@runtime.RuntimeSink]` and delegates file-state reads to the wrapped `RuntimeSink`. + `file_state()` is the compatibility form. For truthful file-semantics detection, prefer `file_state_or_none()`. ### Interface @@ -37,6 +39,7 @@ 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. +- The returned snapshot object itself is the shared `@file_model.FileSinkState` model, not a configured-logger-owned concrete type. - 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()`. diff --git a/docs/api/file-rotation-config-to-json.md b/docs/api/file-rotation-config-to-json.md index b95ff5d..fd4ed31 100644 --- a/docs/api/file-rotation-config-to-json.md +++ b/docs/api/file-rotation-config-to-json.md @@ -13,7 +13,7 @@ key-word: ## File-rotation-config-to-json -Convert `FileRotation` into a `JsonValue`. This helper is the structured export path for file rotation policy when callers need machine-readable config data instead of a runtime policy object. +Convert `FileRotation` into a `JsonValue`. On the root `src` facade, this helper forwards to the concrete serializer owned by `src/file_model`. ### Interface @@ -34,6 +34,7 @@ pub fn file_rotation_config_to_json(config : FileRotation) -> @json_parser.JsonV Detailed rules explaining key parameters and behaviors - The output always includes `max_bytes` and `max_backups`. +- The root surface forwards to `@file_model.file_rotation_config_to_json(...)`, which is the real owner of this serialization logic. - Both of those compatibility fields are exported as JSON numbers. - If the policy carries a wide threshold from `file_rotation_i64(...)`, the output also includes `max_bytes_i64` as a JSON string for exact roundtrip transport. - This helper serializes the rotation config object itself rather than sink availability, failure counters, or file state. diff --git a/docs/api/file-rotation-type.md b/docs/api/file-rotation-type.md index 369a022..67c1199 100644 --- a/docs/api/file-rotation-type.md +++ b/docs/api/file-rotation-type.md @@ -2,8 +2,8 @@ name: file-rotation-type group: api category: sink -update-time: 20260613 -description: Public file rotation alias used for native size-based file sink policy data. +update-time: 20260707 +description: Public file rotation type re-exported from file_model for root file and config APIs. key-word: - file - rotation @@ -13,12 +13,12 @@ key-word: ## File-rotation-type -`FileRotation` is the public file sink rotation policy type used for native size-based log file rollover. It is a direct alias to the sink model that stores the standard byte limit, retained backup count, and additive native wide-threshold metadata for the optional `Int64` path. +`FileRotation` is the public file sink rotation policy type used for size-based log file rollover. On the root `src` facade, it is re-exported from `src/file_model`, which is the real owner of the concrete file rotation model. ### Interface ```moonbit -pub type FileRotation = @utils.FileRotation +pub using @file_model { type FileRotation } ``` #### output @@ -29,10 +29,12 @@ pub type FileRotation = @utils.FileRotation Detailed rules explaining key parameters and behaviors -- This is a type alias, not a file sink or rotation trigger by itself. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@file_model.FileRotation`, not in `@utils` and not in `@file_runtime`. - The current fields are `max_bytes : Int`, `max_backups : Int`, and additive native wide-threshold metadata used by the optional `file_rotation_i64(...)` path. - `file_rotation(...)` constructs this type as the main public helper. - The same value type is consumed by `file_sink(...)`, `FileSinkPolicy::new(...)`, `SinkConfig`, file runtime inspection APIs, and logger config serialization helpers. +- `file_runtime` owns the live `FileSink` behavior that consumes this type, while `runtime` owns higher-level runtime file projections. ### How to Use diff --git a/docs/api/file-sink-policy-to-json.md b/docs/api/file-sink-policy-to-json.md index bf6a304..c0b148b 100644 --- a/docs/api/file-sink-policy-to-json.md +++ b/docs/api/file-sink-policy-to-json.md @@ -13,7 +13,7 @@ key-word: ## File-sink-policy-to-json -Convert `FileSinkPolicy` into a `JsonValue`. This helper exports append mode, auto-flush, and optional rotation as a structured runtime policy snapshot. +Convert `FileSinkPolicy` into a `JsonValue`. On the root `src` facade, this helper forwards to the concrete serializer owned by `src/file_model`. ### Interface @@ -34,6 +34,7 @@ pub fn file_sink_policy_to_json(policy : FileSinkPolicy) -> @json_parser.JsonVal Detailed rules explaining key parameters and behaviors - The output includes `append`, `auto_flush`, and `rotation`. +- The root surface forwards to `@file_model.file_sink_policy_to_json(...)`, which is the real owner of this serialization logic. - `rotation` is exported as `null` when rotation is disabled. - This helper exports runtime file policy, not current file health counters or availability. - The JSON value is useful for policy snapshots, comparisons, and diagnostics payloads. diff --git a/docs/api/file-sink-policy.md b/docs/api/file-sink-policy.md index d807aef..024f63f 100644 --- a/docs/api/file-sink-policy.md +++ b/docs/api/file-sink-policy.md @@ -2,8 +2,8 @@ name: file-sink-policy group: api category: sink -update-time: 20260613 -description: Public file policy alias used by file sinks and runtime file-control APIs. +update-time: 20260707 +description: Public file policy type re-exported from file_model for file and runtime control APIs. key-word: - file - policy @@ -13,12 +13,12 @@ key-word: ## File-sink-policy -`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. It is a direct alias to the file policy model shared by `FileSink`, `RuntimeSink`, `ConfiguredLogger`, and file policy JSON helpers. +`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. On the root `src` facade, it is re-exported from `src/file_model`, which is the real owner of the concrete policy model. ### Interface ```moonbit -pub type FileSinkPolicy = @utils.FileSinkPolicy +pub using @file_model { type FileSinkPolicy } ``` #### output @@ -29,7 +29,8 @@ pub type FileSinkPolicy = @utils.FileSinkPolicy Detailed rules explaining key parameters and behaviors -- This is a type alias, not a separate runtime wrapper. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@file_model.FileSinkPolicy`, not in `@utils`. - The current policy fields are `append : Bool`, `auto_flush : Bool`, and `rotation : FileRotation?`. - The same policy object is returned by `FileSink::policy()`, `RuntimeSink::file_policy()`, and `ConfiguredLogger::file_policy()`. - It is also accepted by `FileSink::set_policy(...)`, `RuntimeSink::file_set_policy(...)`, and `ConfiguredLogger::file_set_policy(...)`. diff --git a/docs/api/file-sink-rotation-failures.md b/docs/api/file-sink-rotation-failures.md index ef30ed7..f4fb4f7 100644 --- a/docs/api/file-sink-rotation-failures.md +++ b/docs/api/file-sink-rotation-failures.md @@ -2,7 +2,7 @@ name: file-sink-rotation-failures group: api category: sink -update-time: 20260613 +update-time: 20260707 description: Read the number of rotation failures recorded by a FileSink. key-word: - file @@ -13,7 +13,7 @@ key-word: ## File-sink-rotation-failures -Read the number of rotation failures recorded by a `FileSink`. This helper is useful when direct runtime rotation behavior should be observed operationally. +Read the number of rotation attempts whose critical file-rotation steps failed for a `FileSink`. ### Interface @@ -34,6 +34,8 @@ pub fn FileSink::rotation_failures(self : FileSink) -> Int { Detailed rules explaining key parameters and behaviors - The sink reports its recorded rotation-failure count directly. +- The counter increases when a rotation attempt cannot complete its critical file steps, such as removing the active file with zero backups, renaming a live file into `.1`, shifting an existing backup to a higher slot, or reopening the fresh active file afterward. +- Missing optional backup slots do not count by themselves; only steps that fail while their source path still exists are treated as rotation failures. - The counter is cumulative until reset. - This helper is observation-only and does not mutate sink state. @@ -48,7 +50,7 @@ When support output should reveal whether direct sink rotation is failing: let count = sink.rotation_failures() ``` -In this example, the concrete file sink exposes a focused metric for rotation-path health. +In this example, the concrete file sink exposes whether a rotation attempt hit a critical file-step failure. #### When Validate Runtime Rotation Tuning @@ -57,17 +59,19 @@ When changed rotation settings should be checked in operation: ignore(sink.rotation_failures()) ``` -In this example, callers can observe whether runtime rotation changes introduced problems. +In this example, callers can observe whether runtime rotation changes started producing incomplete rotations. ### Error Case e.g.: - If callers need both rotation config and failure metrics, they should combine this helper with `rotation_config()` or `state()`. +- This counter alone does not identify which rename/remove/reopen step failed. + - This counter alone does not say whether the sink is currently available. ### Notes -1. Use this helper when diagnosing direct file rotation reliability. +1. Use this helper when diagnosing incomplete direct file rotations. 2. It is especially relevant when runtime rotation policy can change after startup. diff --git a/docs/api/file-sink-state-to-json.md b/docs/api/file-sink-state-to-json.md index f394db7..1f78705 100644 --- a/docs/api/file-sink-state-to-json.md +++ b/docs/api/file-sink-state-to-json.md @@ -13,7 +13,7 @@ key-word: ## File-sink-state-to-json -Convert `FileSinkState` into a `JsonValue`. This helper exports file path, availability, policy flags, rotation config, and failure counters in a structured form. +Convert `FileSinkState` into a `JsonValue`. On the root `src` facade, this helper forwards to the concrete serializer owned by `src/file_model`. ### Interface @@ -34,6 +34,7 @@ pub fn file_sink_state_to_json(state : FileSinkState) -> @json_parser.JsonValue Detailed rules explaining key parameters and behaviors - The output includes `path`, `available`, `append`, `auto_flush`, failure counters, and `rotation`. +- The root surface forwards to `@file_model.file_sink_state_to_json(...)`, which is the real owner of this serialization logic. - `rotation` is exported as `null` when rotation is disabled. - This helper exports state snapshots, not mutable runtime control handles. - It is useful when file sink state should be embedded into larger diagnostics payloads. diff --git a/docs/api/file-sink-state.md b/docs/api/file-sink-state.md index 361fde3..d2d6a53 100644 --- a/docs/api/file-sink-state.md +++ b/docs/api/file-sink-state.md @@ -2,8 +2,8 @@ name: file-sink-state group: api category: runtime -update-time: 20260613 -description: Public file state alias used for live file-sink snapshots and runtime diagnostics. +update-time: 20260707 +description: Public file state type re-exported from file_model for live file-sink snapshots and runtime diagnostics. key-word: - file - state @@ -13,12 +13,12 @@ key-word: ## File-sink-state -`FileSinkState` is the public snapshot object used to describe the current state of a file sink. It is a direct alias to the file state model returned by `FileSink::state()` and by higher-level runtime file inspection helpers. +`FileSinkState` is the public snapshot object used to describe the current state of a file sink. On the root `src` facade, it is re-exported from `src/file_model`, which is the real owner of the concrete file state model. ### Interface ```moonbit -pub type FileSinkState = @utils.FileSinkState +pub using @file_model { type FileSinkState } ``` #### output @@ -29,8 +29,10 @@ pub type FileSinkState = @utils.FileSinkState Detailed rules explaining key parameters and behaviors -- This is a type alias, not a live file handle wrapper. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@file_model.FileSinkState`, not in `@utils`. - The current snapshot fields are `path`, `available`, `append`, `auto_flush`, `rotation`, `open_failures`, `write_failures`, `flush_failures`, and `rotation_failures`. +- `rotation_failures` records how many rotation attempts failed to complete critical remove/rename/reopen steps; it is not a full file-health or backup-integrity audit. - `FileSink::state()` returns this object directly for a concrete file sink. - `RuntimeSink::file_state()` also returns this type, including fallback snapshots for non-file runtime sinks. - `ConfiguredLogger::file_state()` returns the same snapshot type through the config-built runtime wrapper. diff --git a/docs/api/file-sink-type.md b/docs/api/file-sink-type.md index b2cb559..39cf1b5 100644 --- a/docs/api/file-sink-type.md +++ b/docs/api/file-sink-type.md @@ -2,8 +2,8 @@ name: file-sink-type group: api category: sink -update-time: 20260613 -description: Public native file sink type used for file-backed synchronous logging with runtime policy and failure tracking. +update-time: 20260707 +description: Public file sink type re-exported from file_runtime for file-backed synchronous logging. key-word: - sink - file @@ -13,26 +13,12 @@ key-word: ## File-sink-type -`FileSink` is the public native file sink type used for file-backed synchronous logging. It is the concrete sink type returned by `file_sink(...)`, and it stores runtime file policy, availability state, formatter behavior, and failure counters. +`FileSink` is the public file sink type used for file-backed synchronous logging. On the root `src` facade, it is re-exported from `src/file_runtime`, which is the real owner of the concrete sink behavior type. ### Interface ```moonbit -pub struct FileSink { - path : String - append : Ref[Bool] - default_append : Bool - handle : Ref[FileHandle?] - formatter : RecordFormatter - auto_flush : Ref[Bool] - default_auto_flush : Bool - rotation : Ref[FileRotation?] - default_rotation : FileRotation? - open_failures : Ref[Int] - write_failures : Ref[Int] - flush_failures : Ref[Int] - rotation_failures : Ref[Int] -} +pub using @file_runtime { type FileSink } ``` #### output @@ -43,8 +29,9 @@ pub struct FileSink { Detailed rules explaining key parameters and behaviors -- This is a public root struct, not a type alias. -- The current fields cover path, append mode, handle state, formatter, auto-flush policy, optional rotation policy, and failure counters. +- This root surface is a re-export of the concrete `@file_runtime.FileSink` type. +- The struct intentionally hides its fields; callers interact through methods such as `flush()`, `close()`, `reopen()`, `policy()`, and `state()`. +- File model companions such as `FileRotation`, `FileSinkPolicy`, `FileSinkState`, and `RuntimeFileState` are owned by `@file_model`, not by `FileSink` itself. - `file_sink(...)` constructs this type directly from path and policy inputs. - The type exposes runtime helpers such as `flush()`, `close()`, `reopen()`, `policy()`, `state()`, and failure-counter accessors. diff --git a/docs/api/file-sink.md b/docs/api/file-sink.md index 1a7b42c..7e8e566 100644 --- a/docs/api/file-sink.md +++ b/docs/api/file-sink.md @@ -13,7 +13,7 @@ key-word: ## File-sink -Create a native file sink for text-oriented or custom-formatted file logging. This API includes lifecycle controls, rotation configuration, reopen behavior, policy inspection, and failure counters. +Create a native file sink for text-oriented or custom-formatted file logging. On the root `src` facade, this helper forwards to `src/file_runtime`, while the companion file model types it accepts and returns are owned by `src/file_model`. ### Interface @@ -44,6 +44,8 @@ pub fn file_sink( Detailed rules explaining key parameters and behaviors - This sink is designed for host-file capable backends, with current local verification centered on `native`. +- The root `file_sink(...)` entry is a facade over `@file_runtime.file_sink(...)`. +- The accepted `FileRotation` input and the related `FileSinkPolicy` / `FileSinkState` diagnostics types come from `@file_model`. - `llvm` should be treated as experimental in the current release context and was not successfully re-verified in this environment. - The `src` library is still designed for multi-target compilation, but file sink availability remains backend-sensitive inside that broader portable surface. - `append` is persistent policy state and also affects later reopen behavior. diff --git a/docs/api/file.md b/docs/api/file.md index ee91c52..45d5b01 100644 --- a/docs/api/file.md +++ b/docs/api/file.md @@ -13,7 +13,9 @@ key-word: ## File -Create a `LoggerConfig` preset for the built-in file sink. This helper packages file path, append policy, auto-flush behavior, optional rotation, and text formatter settings into a single config object for runtime logger assembly. +Create a `LoggerConfig` preset for the built-in file sink. On the root `src` facade, this helper forwards to the preset builder owned by `src/presets_pkg` and returns a `LoggerConfig` owned by `src/config_model`. + +The optional `rotation` value accepted here is the shared `FileRotation` model owned by `src/file_model`. ### Interface @@ -50,6 +52,8 @@ pub fn file( Detailed rules explaining key parameters and behaviors - This preset always returns `sink.kind=SinkKind::File`. +- The root `file(...)` entry is a facade over `@presets_pkg.file(...)`. +- The returned config shape is the shared `@config_model.LoggerConfig` / `@config_model.SinkConfig` model, not a preset-owned concrete type. - `path` must be non-empty. - `rotation=None` leaves file rotation disabled until a rotation policy is provided directly or through `with_file_rotation(...)`. - `queue=None` by default, so buffering is opt-in through `with_queue(...)`. diff --git a/docs/api/logger-config-type.md b/docs/api/logger-config-type.md index df8a951..5cf7e8b 100644 --- a/docs/api/logger-config-type.md +++ b/docs/api/logger-config-type.md @@ -2,8 +2,8 @@ name: logger-config-type group: api category: config -update-time: 20260613 -description: Public logger config alias used for serializable top-level sync logger settings. +update-time: 20260707 +description: Public logger config type re-exported from config_model for serializable top-level sync settings. key-word: - logger - config @@ -13,12 +13,12 @@ key-word: ## Logger-config-type -`LoggerConfig` is the public top-level serializable config type used to describe sync logger behavior. It is a direct alias to the logger config model used by config parsers, sync logger builders, and async build config embedding. +`LoggerConfig` is the public top-level serializable config type used to describe sync logger behavior. On the root `src` facade, it is re-exported from `src/config_model`, which is the real owner of the concrete logger config model. ### Interface ```moonbit -pub type LoggerConfig = @utils.LoggerConfig +pub using @config_model { type LoggerConfig } ``` #### output @@ -29,7 +29,8 @@ pub type LoggerConfig = @utils.LoggerConfig Detailed rules explaining key parameters and behaviors -- This is a type alias, not a built logger instance. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@config_model.LoggerConfig`, not in `@utils`. - The current fields are `min_level : Level`, `target : String`, `timestamp : Bool`, `sink : SinkConfig`, and `queue : QueueConfig?`. - `LoggerConfig::new(...)` constructs this type as the main sync config entry point. - `parse_logger_config_text(...)`, `logger_config_to_json(...)`, `stringify_logger_config(...)`, and `build_logger(...)` all consume or produce the same public config shape. diff --git a/docs/api/parse-and-build-logger.md b/docs/api/parse-and-build-logger.md index 907a9e1..e057e4b 100644 --- a/docs/api/parse-and-build-logger.md +++ b/docs/api/parse-and-build-logger.md @@ -15,6 +15,8 @@ key-word: Parse a JSON logger definition and build a ready-to-use `ConfiguredLogger`. This is the most direct API when configuration is loaded from files, environment-derived JSON, or external settings systems. +At the public `src` layer, this API is a facade composition of the root parser and root builder: it parses into the shared config model owned by `src/config_model`, then produces a `ConfiguredLogger` backed by `src/runtime.RuntimeSink`. + ### Interface ```moonbit @@ -34,6 +36,7 @@ pub fn parse_and_build_logger(input : String) -> ConfiguredLogger raise ConfigEr Detailed rules explaining key parameters and behaviors - Parsing and building are done in one step by calling `parse_logger_config_text(input)` first and then passing the resulting `LoggerConfig` into `build_logger(...)`. +- The resulting file-control and file-diagnostics helpers remain facade methods over `RuntimeSink`, which in turn delegates file behavior to `src/file_runtime` and file model values to `src/file_model`. - The returned `ConfiguredLogger` is just `Logger[RuntimeSink]`, so it still supports regular logging calls. - The returned logger also keeps inherited logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - That means `log(..., target=...)` can override the target for one write, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`. diff --git a/docs/api/parse-logger-config-text.md b/docs/api/parse-logger-config-text.md index cea3ef7..ed52ea6 100644 --- a/docs/api/parse-logger-config-text.md +++ b/docs/api/parse-logger-config-text.md @@ -15,6 +15,8 @@ key-word: Parse JSON text into a typed `LoggerConfig`. This API is useful when you want validation and inspection of config data before turning it into a runtime logger. +At the public `src` layer, this parser is a facade over the concrete config parser owned by `src/config_model`, and the returned config object is the shared `@config_model.LoggerConfig` model. + ### Interface ```moonbit @@ -34,6 +36,7 @@ pub fn parse_logger_config_text(input : String) -> LoggerConfig raise ConfigErro Detailed rules explaining key parameters and behaviors - Parsing is separated from runtime construction. +- Any parsed file rotation field is stored as the shared `@file_model.FileRotation` model inside `SinkConfig.rotation`. - This API is ideal for validating, editing, or inspecting config values before calling `build_logger(...)`. - Supported keys are intentionally constrained to stable built-in sink shapes and formatter options. - Omitted top-level keys fall back to the same defaults used by the typed config constructors: `min_level=Info`, `target=""`, `timestamp=false`, `sink=default_sink_config()`, and `queue=None`. diff --git a/docs/api/queue-config-type.md b/docs/api/queue-config-type.md index e5b4b79..4cbbcbe 100644 --- a/docs/api/queue-config-type.md +++ b/docs/api/queue-config-type.md @@ -2,8 +2,8 @@ name: queue-config-type group: api category: config -update-time: 20260613 -description: Public queue config alias used for serializable synchronous queue wrapping settings. +update-time: 20260707 +description: Public queue config type re-exported from config_model for serializable sync queue settings. key-word: - queue - config @@ -13,12 +13,12 @@ key-word: ## Queue-config-type -`QueueConfig` is the public serializable config type used to describe synchronous queue wrapping. It is a direct alias to the queue config model used by sync logger configuration, parsers, and queue config serializers. +`QueueConfig` is the public serializable config type used to describe synchronous queue wrapping. On the root `src` facade, it is re-exported from `src/config_model`, which is the real owner of the concrete queue config model. ### Interface ```moonbit -pub type QueueConfig = @utils.QueueConfig +pub using @config_model { type QueueConfig } ``` #### output @@ -29,7 +29,8 @@ pub type QueueConfig = @utils.QueueConfig Detailed rules explaining key parameters and behaviors -- This is a type alias, not a runtime queue instance. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@config_model.QueueConfig`, not in `@utils`. - The current fields are `max_pending : Int` and `overflow : QueueOverflowPolicy`. - `QueueConfig::new(...)` constructs this type as the normal handwritten entry point. - `queue_config_to_json(...)` and `stringify_queue_config(...)` serialize the same public config shape for tooling or persistence. diff --git a/docs/api/queue-overflow-policy.md b/docs/api/queue-overflow-policy.md index 19ed20e..872944b 100644 --- a/docs/api/queue-overflow-policy.md +++ b/docs/api/queue-overflow-policy.md @@ -13,12 +13,12 @@ key-word: ## Queue-overflow-policy -`QueueOverflowPolicy` is the public enum that defines what a synchronous queue should do when it reaches `max_pending`. It is a direct alias to the queue model enum used by both `QueuedSink` and `QueueConfig`. +`QueueOverflowPolicy` is the public enum that defines what a synchronous queue should do when it reaches `max_pending`. It is a direct alias to the shared queue model enum used by both `QueuedSink` and `QueueConfig`. ### Interface ```moonbit -pub type QueueOverflowPolicy = @utils.QueueOverflowPolicy +pub type QueueOverflowPolicy = @queue_model.QueueOverflowPolicy ``` #### output @@ -32,6 +32,7 @@ Detailed rules explaining key parameters and behaviors - This is a type alias, not a separate policy wrapper. - `QueueOverflowPolicy::DropNewest` keeps the existing queued records and drops the incoming one when the queue is full. - `QueueOverflowPolicy::DropOldest` removes one pending record and enqueues the new record instead. +- The concrete owner is the shared `@queue_model` package, so config-side and sink-side queue APIs reference the same model without making config packages depend on sink runtime packages. - The same enum is used by code-side queue composition through `queued_sink(...)` and config-driven queue composition through `QueueConfig::new(...)`. ### How to Use diff --git a/docs/api/queued-sink-type.md b/docs/api/queued-sink-type.md index a0ef515..e782a1c 100644 --- a/docs/api/queued-sink-type.md +++ b/docs/api/queued-sink-type.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - This is a public root struct, not a type alias. - The current fields are `sink : S`, `queue : @queue.Queue[Record]`, `max_pending : Int`, `overflow : QueueOverflowPolicy`, and `dropped_count : Ref[Int]`. +- The `overflow` field resolves to the shared `@queue_model.QueueOverflowPolicy` owner. - `queued_sink(...)` constructs this type directly from a wrapped sink and queue policy. - The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after queueing is introduced. diff --git a/docs/api/runtime-file-state-to-json.md b/docs/api/runtime-file-state-to-json.md index e5ee687..96bd7d1 100644 --- a/docs/api/runtime-file-state-to-json.md +++ b/docs/api/runtime-file-state-to-json.md @@ -13,7 +13,7 @@ key-word: ## Runtime-file-state-to-json -Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and queue metrics for combined runtime file diagnostics. +Convert `RuntimeFileState` into a `JsonValue`. On the root `src` facade, this helper forwards to the concrete serializer owned by `src/file_model`. ### Interface @@ -34,6 +34,7 @@ pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.Json Detailed rules explaining key parameters and behaviors - The output includes `file`, `queued`, `pending_count`, and `dropped_count`. +- The root surface forwards to `@file_model.runtime_file_state_to_json(...)`, which is the real owner of this serialization logic. - `file` is itself exported as a nested file sink state object. - This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context. - It is useful for `RuntimeSink::file_runtime_state()`, `ConfiguredLogger::file_runtime_state()`, and similar queued-file diagnostics flows. diff --git a/docs/api/runtime-file-state.md b/docs/api/runtime-file-state.md index a6cba7d..ae913cf 100644 --- a/docs/api/runtime-file-state.md +++ b/docs/api/runtime-file-state.md @@ -2,8 +2,8 @@ name: runtime-file-state group: api category: runtime -update-time: 20260613 -description: Public combined file-and-queue runtime state alias used by runtime file diagnostics. +update-time: 20260707 +description: Public combined file-and-queue runtime state re-exported from file_model for runtime diagnostics. key-word: - runtime - file @@ -13,12 +13,12 @@ key-word: ## Runtime-file-state -`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for file-backed runtime diagnostics. It is a direct alias to the runtime model used by `RuntimeSink`, `ConfiguredLogger`, and JSON export helpers. +`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for file-backed runtime diagnostics. On the root `src` facade, it is re-exported from `src/file_model`, which is the real owner of the concrete runtime file state model. ### Interface ```moonbit -pub type RuntimeFileState = @utils.RuntimeFileState +pub using @file_model { type RuntimeFileState } ``` #### output @@ -29,7 +29,8 @@ pub type RuntimeFileState = @utils.RuntimeFileState Detailed rules explaining key parameters and behaviors -- This is a type alias, not a live runtime controller. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@file_model.RuntimeFileState`, not in `@utils`. - The current fields are `file : FileSinkState`, `queued : Bool`, `pending_count : Int`, and `dropped_count : Int`. - This type is returned by `RuntimeSink::file_runtime_state()` and by `ConfiguredLogger::file_runtime_state()` when file runtime context is available. - It is broader than `FileSinkState` because it also reports whether queue wrapping is involved and how the queue is behaving. diff --git a/docs/api/runtime-sink-file-default-policy-or-none.md b/docs/api/runtime-sink-file-default-policy-or-none.md index b89a239..d3e59ad 100644 --- a/docs/api/runtime-sink-file-default-policy-or-none.md +++ b/docs/api/runtime-sink-file-default-policy-or-none.md @@ -15,6 +15,8 @@ key-word: Read the default runtime file policy from a `RuntimeSink` only when it is actually file-backed. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this method belongs to the runtime facade layer and avoids fabricating that model on non-file variants. + 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 @@ -37,6 +39,7 @@ 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)`. +- The wrapped value is the shared `@file_model.FileSinkPolicy` model, not a runtime-owned concrete type. - Non-file runtime variants return `None`. - This helper is useful when callers need to compare runtime drift or restore defaults without fabricating file semantics. diff --git a/docs/api/runtime-sink-file-default-policy.md b/docs/api/runtime-sink-file-default-policy.md index 40b2dc5..7b67431 100644 --- a/docs/api/runtime-sink-file-default-policy.md +++ b/docs/api/runtime-sink-file-default-policy.md @@ -15,6 +15,8 @@ key-word: Read the initial default file policy associated with a `RuntimeSink`. This helper exposes the baseline file policy captured when the runtime sink was created. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this method belongs to the runtime facade layer and reads defaults through `src/runtime` over file-backed variants that ultimately use `src/file_runtime.FileSink`. + ### Interface ```moonbit @@ -35,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants return the default policy captured at creation time. - `QueuedFile` runtime variants forward the default policy from the wrapped inner `FileSink`. +- The returned policy object itself is the shared `@file_model.FileSinkPolicy` model, not a runtime-owned concrete type. - Non-file runtime variants return the neutral fallback policy `FileSinkPolicy::new(append=false, auto_flush=false, rotation=None)`. - This helper is useful when callers need to compare runtime drift or restore defaults later. diff --git a/docs/api/runtime-sink-file-policy.md b/docs/api/runtime-sink-file-policy.md index 15f70a1..c54147b 100644 --- a/docs/api/runtime-sink-file-policy.md +++ b/docs/api/runtime-sink-file-policy.md @@ -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. +The returned `FileSinkPolicy` value is owned by `src/file_model`; this method is part of the runtime facade layer and reads or synthesizes policy through `src/runtime` over file-backed variants that ultimately use `src/file_runtime.FileSink`. + `file_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_policy_or_none()`. ### Interface @@ -37,6 +39,7 @@ 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`. +- The returned policy object itself is the shared `@file_model.FileSinkPolicy` model, not a runtime-owned concrete type. - 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()`. diff --git a/docs/api/runtime-sink-file-rotation-config.md b/docs/api/runtime-sink-file-rotation-config.md index 102aff8..85d0c65 100644 --- a/docs/api/runtime-sink-file-rotation-config.md +++ b/docs/api/runtime-sink-file-rotation-config.md @@ -15,6 +15,8 @@ key-word: Read the current rotation configuration used by a file-backed `RuntimeSink`. This helper exposes active direct runtime rotation parameters when rotation is enabled. +The returned `FileRotation` value is owned by `src/file_model`; this method belongs to the runtime facade layer and reads rotation policy through `src/runtime` over file-backed variants that ultimately use `src/file_runtime.FileSink`. + ### Interface ```moonbit @@ -35,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants return the current rotation config from the wrapped `FileSink`. - `QueuedFile` runtime variants forward the config from the wrapped inner `FileSink`. +- The returned rotation object itself is the shared `@file_model.FileRotation` model, not a runtime-owned concrete type. - Non-file runtime variants return `None`. - This helper is useful when callers need the active direct runtime policy rather than only a boolean flag. diff --git a/docs/api/runtime-sink-file-rotation-failures.md b/docs/api/runtime-sink-file-rotation-failures.md index aa0ff01..62b360f 100644 --- a/docs/api/runtime-sink-file-rotation-failures.md +++ b/docs/api/runtime-sink-file-rotation-failures.md @@ -2,7 +2,7 @@ name: runtime-sink-file-rotation-failures group: api category: runtime -update-time: 20260613 +update-time: 20260707 description: Read the number of rotation failures recorded by a file-backed RuntimeSink. key-word: - runtime @@ -13,7 +13,7 @@ key-word: ## Runtime-sink-file-rotation-failures -Read the number of rotation failures recorded by a file-backed `RuntimeSink`. This helper is useful when direct runtime rotation behavior should be observed operationally. +Read the number of file-rotation attempts whose critical file steps failed in a file-backed `RuntimeSink`. ### Interface @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants report the wrapped `FileSink` rotation-failure count. - `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`. - Non-file runtime variants return `0`. +- For file-backed variants, the counter covers incomplete rotations caused by critical remove/rename/reopen failures, not merely policy changes or missing optional backup slots. - The counter is cumulative until `file_reset_failure_counters()` clears it. ### How to Use @@ -49,7 +50,7 @@ When support output should reveal whether rotation is failing: let count = sink.file_rotation_failures() ``` -In this example, the runtime sink exposes a focused metric for direct rotation-path health. +In this example, the runtime sink exposes whether direct file rotation stopped completing its critical steps. #### When Validate Runtime Rotation Tuning @@ -58,7 +59,7 @@ When changed rotation settings should be checked in operation: ignore(sink.file_rotation_failures()) ``` -In this example, callers can observe whether runtime rotation changes introduced problems. +In this example, callers can observe whether runtime rotation changes introduced incomplete rotations. ### Error Case @@ -67,8 +68,10 @@ e.g.: - If callers need both rotation config and failure metrics, they should combine this helper with `file_rotation_config()` or `file_state()`. +- This counter does not expose which low-level step failed inside the rotation chain. + ### Notes -1. Use this helper when diagnosing direct runtime file rotation reliability. +1. Use this helper when diagnosing incomplete direct runtime file rotations. 2. It is especially relevant when runtime rotation policy can change after startup. diff --git a/docs/api/runtime-sink-file-runtime-state.md b/docs/api/runtime-sink-file-runtime-state.md index f173f8a..dbe34d6 100644 --- a/docs/api/runtime-sink-file-runtime-state.md +++ b/docs/api/runtime-sink-file-runtime-state.md @@ -15,6 +15,8 @@ key-word: Read combined file and queue runtime state from a `RuntimeSink`. This helper is the richest file-specific diagnostics API on direct runtime sink values. +The returned `RuntimeFileState` value is owned by `src/file_model`; this method belongs to the runtime facade layer in `src/runtime` and combines file snapshots from `src/file_runtime.FileSink` with outer queue metrics. + ### Interface ```moonbit @@ -35,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants return `Some(RuntimeFileState::new(sink.state()))`, so queue metadata stays at its default non-queued shape. - `QueuedFile` runtime variants return `Some(RuntimeFileState)` with the wrapped file state plus `queued=true`, `pending_count=sink.pending_count()`, and `dropped_count=sink.dropped_count()`. +- The returned snapshot object itself is the shared `@file_model.RuntimeFileState` model, not a runtime-owned concrete type. - Non-file runtime variants return `None`. - This helper is richer than `file_state()` because it can also surface queued backlog and dropped counts. diff --git a/docs/api/runtime-sink-file-set-policy.md b/docs/api/runtime-sink-file-set-policy.md index 916d8d6..2ec1682 100644 --- a/docs/api/runtime-sink-file-set-policy.md +++ b/docs/api/runtime-sink-file-set-policy.md @@ -15,6 +15,8 @@ key-word: Apply a bundled runtime file policy update to a `RuntimeSink`. This helper updates append mode, auto-flush, and rotation together through one runtime policy object on direct sink values. +The input `FileSinkPolicy` value is owned by `src/file_model`; this method belongs to the runtime facade layer and forwards policy mutation through `src/runtime` to file-backed variants that ultimately use `src/file_runtime.FileSink`. + ### Interface ```moonbit @@ -36,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants update append, auto-flush, and rotation together on the wrapped `FileSink` and return `true`. - `QueuedFile` runtime variants forward the policy update to the wrapped inner `FileSink` only when no queued records are pending. +- The accepted policy object itself is the shared `@file_model.FileSinkPolicy` model, not a runtime-owned concrete type. - Non-file runtime variants return `false`. - This helper is broader than the single-setting setters because it updates the whole file policy in one call. - If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different policy bundle than the one they were queued under. diff --git a/docs/api/runtime-sink-file-set-rotation.md b/docs/api/runtime-sink-file-set-rotation.md index 2e5369c..94972b2 100644 --- a/docs/api/runtime-sink-file-set-rotation.md +++ b/docs/api/runtime-sink-file-set-rotation.md @@ -15,6 +15,8 @@ key-word: Update the rotation policy used by a file-backed `RuntimeSink`. +The input `FileRotation` value is owned by `src/file_model`; this method belongs to the runtime facade layer and forwards rotation mutation through `src/runtime` to file-backed variants that ultimately use `src/file_runtime.FileSink`. + ### Interface ```moonbit @@ -36,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants update the wrapped `FileSink` rotation policy and return `true`. - `QueuedFile` runtime variants forward the update to the wrapped inner `FileSink` only when no queued records are pending. +- The accepted rotation object itself is the shared `@file_model.FileRotation` model, not a runtime-owned concrete type. - Non-file runtime variants return `false`. - This helper changes policy only; it does not itself rotate or flush pending data. - If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different rotation policy than the one they were queued under. diff --git a/docs/api/runtime-sink-file-state.md b/docs/api/runtime-sink-file-state.md index e523d22..382088f 100644 --- a/docs/api/runtime-sink-file-state.md +++ b/docs/api/runtime-sink-file-state.md @@ -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. +The returned `FileSinkState` value is owned by `src/file_model`; this method belongs to the runtime facade layer and reads file snapshots through `src/runtime` over file-backed variants that ultimately use `src/file_runtime.FileSink`. + `file_state()` is the compatibility form. For truthful file-semantics detection, prefer `file_state_or_none()`. ### Interface @@ -37,6 +39,7 @@ 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`. +- The returned snapshot object itself is the shared `@file_model.FileSinkState` model, not a runtime-owned concrete type. - 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()`. diff --git a/docs/api/sink-config-type.md b/docs/api/sink-config-type.md index ffbdc52..93aaa12 100644 --- a/docs/api/sink-config-type.md +++ b/docs/api/sink-config-type.md @@ -2,8 +2,8 @@ name: sink-config-type group: api category: config -update-time: 20260613 -description: Public sink config alias used for serializable built-in sink selection and settings. +update-time: 20260707 +description: Public sink config type re-exported from config_model for serializable built-in sink settings. key-word: - sink - config @@ -13,12 +13,12 @@ key-word: ## Sink-config-type -`SinkConfig` is the public serializable config type used to describe the built-in sink shape and its related settings. It is a direct alias to the sink config model used by config parsing, logger building, and sink config serializers. +`SinkConfig` is the public serializable config type used to describe the built-in sink shape and its related settings. On the root `src` facade, it is re-exported from `src/config_model`, which is the real owner of the concrete sink config model. ### Interface ```moonbit -pub type SinkConfig = @utils.SinkConfig +pub using @config_model { type SinkConfig } ``` #### output @@ -29,7 +29,8 @@ pub type SinkConfig = @utils.SinkConfig Detailed rules explaining key parameters and behaviors -- This is a type alias, not a runtime sink instance. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@config_model.SinkConfig`, not in `@utils`. - The current fields are `kind : SinkKind`, `path : String`, `append : Bool`, `auto_flush : Bool`, `rotation : FileRotation?`, and `text_formatter : TextFormatterConfig`. - `SinkConfig::new(...)` constructs this type as the main code-side entry point. - `sink_config_to_json(...)`, `stringify_sink_config(...)`, and `build_logger(...)` all consume the same public config shape. diff --git a/docs/api/sink-kind.md b/docs/api/sink-kind.md index 74649df..7f508bd 100644 --- a/docs/api/sink-kind.md +++ b/docs/api/sink-kind.md @@ -2,8 +2,8 @@ name: sink-kind group: api category: config -update-time: 20260613 -description: Public sink kind enum alias used by SinkConfig and config parsing. +update-time: 20260707 +description: Public sink kind enum re-exported from config_model for built-in sink selection. key-word: - sink - config @@ -13,12 +13,12 @@ key-word: ## Sink-kind -`SinkKind` is the public enum that selects which built-in sink shape a `SinkConfig` should build. It is a direct alias to the internal config enum, so config builders, JSON parsers, and sink serialization helpers all use the same small set of variants. +`SinkKind` is the public enum that selects which built-in sink shape a `SinkConfig` should build. On the root `src` facade, it is re-exported from `src/config_model`, so config builders, JSON parsers, and sink serialization helpers all use the same small set of variants. ### Interface ```moonbit -pub type SinkKind = @utils.SinkKind +pub using @config_model { type SinkKind } ``` #### output @@ -29,7 +29,8 @@ pub type SinkKind = @utils.SinkKind Detailed rules explaining key parameters and behaviors -- This is a type alias, not a wrapper or a new runtime sink implementation. +- This root surface is a re-export, not the concrete owner definition. +- The concrete enum lives in `@config_model.SinkKind`, not in `@utils`. - `SinkKind::Console` selects the basic text console sink. - `SinkKind::JsonConsole` selects JSON line output. - `SinkKind::TextConsole` selects text console output driven by `TextFormatterConfig`. diff --git a/docs/api/stringify-file-sink-policy.md b/docs/api/stringify-file-sink-policy.md index 74c53af..2e3ce4c 100644 --- a/docs/api/stringify-file-sink-policy.md +++ b/docs/api/stringify-file-sink-policy.md @@ -13,7 +13,7 @@ key-word: ## Stringify-file-sink-policy -Serialize `FileSinkPolicy` into JSON text. This helper is the most direct export path for runtime file policy snapshots. +Serialize `FileSinkPolicy` into JSON text. On the root `src` facade, this helper forwards to the concrete stringifier owned by `src/file_model`. ### Interface @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON. - `pretty=true` returns indented JSON for human inspection. +- The root surface forwards to `@file_model.stringify_file_sink_policy(...)`, which is the real owner of this formatting logic. - This helper builds on top of `file_sink_policy_to_json(...)`. - The output is suited for support dumps, policy snapshots, and generated diagnostics text. - Typical inputs come from `FileSink::policy()`, `RuntimeSink::file_policy()`, or `ConfiguredLogger::file_policy()`. diff --git a/docs/api/stringify-file-sink-state.md b/docs/api/stringify-file-sink-state.md index cf8f731..96d7872 100644 --- a/docs/api/stringify-file-sink-state.md +++ b/docs/api/stringify-file-sink-state.md @@ -13,7 +13,7 @@ key-word: ## Stringify-file-sink-state -Serialize `FileSinkState` into JSON text. This helper is the most direct export path for file sink diagnostics snapshots. +Serialize `FileSinkState` into JSON text. On the root `src` facade, this helper forwards to the concrete stringifier owned by `src/file_model`. ### Interface @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON. - `pretty=true` returns indented JSON for human diagnostics. +- The root surface forwards to `@file_model.stringify_file_sink_state(...)`, which is the real owner of this formatting logic. - This helper builds on top of `file_sink_state_to_json(...)`. - The output is well-suited for support dumps, incident reports, and log snapshots. - Typical inputs come from `FileSink::state()`, `RuntimeSink::file_state()`, or `ConfiguredLogger::file_state()`. diff --git a/docs/api/stringify-runtime-file-state.md b/docs/api/stringify-runtime-file-state.md index db594b0..0830aa1 100644 --- a/docs/api/stringify-runtime-file-state.md +++ b/docs/api/stringify-runtime-file-state.md @@ -13,7 +13,7 @@ key-word: ## Stringify-runtime-file-state -Serialize `RuntimeFileState` into JSON text. This helper is the most direct export path for combined file-and-queue runtime diagnostics. +Serialize `RuntimeFileState` into JSON text. On the root `src` facade, this helper forwards to the concrete stringifier owned by `src/file_model`. ### Interface @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON. - `pretty=true` returns indented JSON for human diagnostics. +- The root surface forwards to `@file_model.stringify_runtime_file_state(...)`, which is the real owner of this formatting logic. - This helper builds on top of `runtime_file_state_to_json(...)`. - The output is useful when queued file runtime state should be printed directly during support or incident handling. - Typical inputs come from `RuntimeSink::file_runtime_state()` or `ConfiguredLogger::file_runtime_state()`. diff --git a/docs/api/text-formatter-config-type.md b/docs/api/text-formatter-config-type.md index 7a46048..47b0ee9 100644 --- a/docs/api/text-formatter-config-type.md +++ b/docs/api/text-formatter-config-type.md @@ -2,8 +2,8 @@ name: text-formatter-config-type group: api category: config -update-time: 20260613 -description: Public text formatter config alias used for serializable formatter settings. +update-time: 20260707 +description: Public text formatter config type re-exported from config_model for serializable formatter settings. key-word: - formatter - config @@ -13,12 +13,12 @@ key-word: ## Text-formatter-config-type -`TextFormatterConfig` is the public serializable config type used to describe text rendering behavior. It is a direct alias to the formatter config model used by config parsing, config serialization, and runtime formatter conversion. +`TextFormatterConfig` is the public serializable config type used to describe text rendering behavior. On the root `src` facade, it is re-exported from `src/config_model`, which is the real owner of the concrete formatter config model. ### Interface ```moonbit -pub type TextFormatterConfig = @utils.TextFormatterConfig +pub using @config_model { type TextFormatterConfig } ``` #### output @@ -29,7 +29,8 @@ pub type TextFormatterConfig = @utils.TextFormatterConfig Detailed rules explaining key parameters and behaviors -- This is a type alias, not a runtime `TextFormatter` instance. +- This root surface is a re-export, not the concrete owner definition. +- The concrete type lives in `@config_model.TextFormatterConfig`, not in `@utils`. - The current fields are `show_timestamp`, `show_level`, `show_target`, `show_fields`, `separator`, `field_separator`, `template`, `color_mode`, `color_support`, `style_markup`, `target_style_markup`, `fields_style_markup`, and `style_tags`. - `TextFormatterConfig::new(...)` constructs this type as the main code-side entry point. - `text_formatter_config_to_json(...)`, `stringify_text_formatter_config(...)`, and `TextFormatterConfig::to_formatter()` all consume the same public config shape. diff --git a/docs/api/with-file-rotation-i64.md b/docs/api/with-file-rotation-i64.md index 5203101..dec65d4 100644 --- a/docs/api/with-file-rotation-i64.md +++ b/docs/api/with-file-rotation-i64.md @@ -13,7 +13,7 @@ key-word: ## With-file-rotation-i64 -Add or replace a size-based file rotation policy with an `Int64` byte threshold on an existing `LoggerConfig`. This helper is the additive native-focused counterpart to `with_file_rotation(...)` for large-file rotation thresholds. +Add or replace a size-based file rotation policy with an `Int64` byte threshold on an existing `LoggerConfig`. On the root `src` facade, this helper forwards to the preset builder owned by `src/presets_pkg` and rewrites the shared config model owned by `src/config_model`. ### Interface @@ -38,6 +38,8 @@ pub fn with_file_rotation_i64( ### Explanation - `with_file_rotation_i64(...)` only applies to file presets or other configs whose `sink.kind=SinkKind::File`. +- The root `with_file_rotation_i64(...)` entry is a facade over `@presets_pkg.with_file_rotation_i64(...)`. +- The resulting `sink.rotation` field still uses the shared `@file_model.FileRotation` model, with the wide threshold preserved inside that file-model-owned type. - If the input config is not file-based, the helper returns the config unchanged. - When the input config is file-based, the helper preserves all existing config fields while replacing `sink.rotation` with a wide native-focused policy. - Rotation policy creation follows `file_rotation_i64(...)` normalization rules. diff --git a/docs/api/with-file-rotation.md b/docs/api/with-file-rotation.md index b1e610b..e9fbb27 100644 --- a/docs/api/with-file-rotation.md +++ b/docs/api/with-file-rotation.md @@ -13,7 +13,7 @@ key-word: ## With-file-rotation -Add or replace a size-based file rotation policy on an existing `LoggerConfig`. This helper is intentionally narrow: it only mutates configs whose sink kind is `File` and leaves every non-file config unchanged. +Add or replace a size-based file rotation policy on an existing `LoggerConfig`. On the root `src` facade, this helper forwards to the preset builder owned by `src/presets_pkg` and rewrites the shared config model owned by `src/config_model`. ### Interface @@ -40,6 +40,8 @@ pub fn with_file_rotation( Detailed rules explaining key parameters and behaviors - `with_file_rotation(...)` only applies to file presets or other configs whose `sink.kind=SinkKind::File`. +- The root `with_file_rotation(...)` entry is a facade over `@presets_pkg.with_file_rotation(...)`. +- The resulting `sink.rotation` field still uses the shared `@file_model.FileRotation` model. - If the input config is not file-based, the helper returns the config unchanged. - When the input config is file-based, the helper preserves `min_level`, `target`, `timestamp`, file path, append mode, auto-flush, formatter, and queue settings while replacing `sink.rotation`. - Rotation policy creation follows `file_rotation(...)` normalization rules for `max_bytes` and `max_backups`.