📝 align sync API docs with owner packages

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(...)`.

docs/api/config-error.md

@@ -2,8 +2,8 @@
 name: config-error
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public config parsing error alias used by synchronous config-loading helpers.
+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.

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.
 

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()`.

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()`.

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.
 

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.

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.
 

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.

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.

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()`.

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.

docs/api/file-rotation-type.md

@@ -2,8 +2,8 @@
 name: file-rotation-type
 group: api
 category: sink
-update-time: 20260613
+update-time: 20260707
-description: Public file rotation alias used for native size-based file sink policy data.
+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
 

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.

docs/api/file-sink-policy.md

@@ -2,8 +2,8 @@
 name: file-sink-policy
 group: api
 category: sink
-update-time: 20260613
+update-time: 20260707
-description: Public file policy alias used by file sinks and runtime file-control APIs.
+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(...)`.

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.

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.

docs/api/file-sink-state.md

@@ -2,8 +2,8 @@
 name: file-sink-state
 group: api
 category: runtime
-update-time: 20260613
+update-time: 20260707
-description: Public file state alias used for live file-sink snapshots and runtime diagnostics.
+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.

docs/api/file-sink-type.md

@@ -2,8 +2,8 @@
 name: file-sink-type
 group: api
 category: sink
-update-time: 20260613
+update-time: 20260707
-description: Public native file sink type used for file-backed synchronous logging with runtime policy and failure tracking.
+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 {
+pub using @file_runtime { type 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]
-}
 ```
 
 #### 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.
+- This root surface is a re-export of the concrete `@file_runtime.FileSink` type.
-- The current fields cover path, append mode, handle state, formatter, auto-flush policy, optional rotation policy, and failure counters.
+- 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.
 

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.

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(...)`.

docs/api/logger-config-type.md

@@ -2,8 +2,8 @@
 name: logger-config-type
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public logger config alias used for serializable top-level sync logger settings.
+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.

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(...)`.

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`.

docs/api/queue-config-type.md

@@ -2,8 +2,8 @@
 name: queue-config-type
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public queue config alias used for serializable synchronous queue wrapping settings.
+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.

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

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.
 

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.

docs/api/runtime-file-state.md

@@ -2,8 +2,8 @@
 name: runtime-file-state
 group: api
 category: runtime
-update-time: 20260613
+update-time: 20260707
-description: Public combined file-and-queue runtime state alias used by runtime file diagnostics.
+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.

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.
 

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.
 

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()`.

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.
 

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.

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.
 

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.

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.

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()`.

docs/api/sink-config-type.md

@@ -2,8 +2,8 @@
 name: sink-config-type
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public sink config alias used for serializable built-in sink selection and settings.
+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.

docs/api/sink-kind.md

@@ -2,8 +2,8 @@
 name: sink-kind
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public sink kind enum alias used by SinkConfig and config parsing.
+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`.

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()`.

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()`.

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()`.

docs/api/text-formatter-config-type.md

@@ -2,8 +2,8 @@
 name: text-formatter-config-type
 group: api
 category: config
-update-time: 20260613
+update-time: 20260707
-description: Public text formatter config alias used for serializable formatter settings.
+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.

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.

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`.