📝 document public config and level aliases

docs/api/async-flush-policy.md

@@ -0,0 +1,71 @@
+---
+name: async-flush-policy
+group: api
+category: async
+update-time: 20260613
+description: Public flush policy alias used by AsyncLoggerConfig and async worker flushing.
+key-word:
+    - async
+    - flush
+    - alias
+    - public
+---
+
+## Async-flush-policy
+
+`AsyncFlushPolicy` is the public enum that defines when an async logger should call its flush function. It is a direct alias to the async model enum used by `AsyncLoggerConfig`, worker execution, and async logger state reporting.
+
+### Interface
+
+```moonbit
+pub type AsyncFlushPolicy = @utils.AsyncFlushPolicy
+```
+
+#### output
+
+- `AsyncFlushPolicy` - Public async flush enum with the variants `Never`, `Batch`, and `Shutdown`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate lifecycle wrapper.
+- `AsyncFlushPolicy::Never` skips explicit flush calls from the async worker.
+- `AsyncFlushPolicy::Batch` calls the configured flush function after each processed batch.
+- `AsyncFlushPolicy::Shutdown` calls the configured flush function once after the worker loop exits.
+- The current flush policy is also exposed through `AsyncLogger::flush_policy()` and included in `AsyncLoggerState`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Explicit Flush After Every Processed Batch
+
+When buffered sinks should flush incrementally during worker execution:
+```moonbit
+let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Batch)
+```
+
+In this example, each batch run triggers the provided flush callback.
+
+#### When Need One Final Flush During Shutdown
+
+When sink flushing should be deferred until the worker finishes:
+```moonbit
+let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Shutdown)
+```
+
+In this example, flushing happens when the worker loop exits instead of after each batch.
+
+### Error Case
+
+e.g.:
+- If async config text uses unsupported flush policy text, async config parsing raises a failure.
+
+- If a sink never needs explicit flushing, `Batch` or `Shutdown` can add unnecessary work without changing output.
+
+### Notes
+
+1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.
+
+2. `AsyncFlushPolicy::Never` is the default in `AsyncLoggerConfig::new(...)`.

docs/api/async-overflow-policy.md

@@ -0,0 +1,71 @@
+---
+name: async-overflow-policy
+group: api
+category: async
+update-time: 20260613
+description: Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.
+key-word:
+    - async
+    - overflow
+    - alias
+    - public
+---
+
+## Async-overflow-policy
+
+`AsyncOverflowPolicy` is the public enum that controls what an `AsyncLogger` should do when its queue cannot accept a record immediately. It is a direct alias to the async model enum used by `AsyncLoggerConfig` and the runtime queue selection logic.
+
+### Interface
+
+```moonbit
+pub type AsyncOverflowPolicy = @utils.AsyncOverflowPolicy
+```
+
+#### output
+
+- `AsyncOverflowPolicy` - Public async queue overflow enum with the variants `Blocking`, `DropOldest`, and `DropNewest`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate runtime adapter.
+- `AsyncOverflowPolicy::Blocking` waits for queue space when a non-blocking enqueue does not succeed.
+- `AsyncOverflowPolicy::DropOldest` lets the underlying async queue discard older pending records when capacity is limited.
+- `AsyncOverflowPolicy::DropNewest` discards the incoming record instead of blocking.
+- The same enum is used by `AsyncLoggerConfig::new(...)`, async config parsing, and the queue-kind mapping inside `AsyncLogger`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Backpressure Instead Of Silent Dropping
+
+When producers should wait for queue space:
+```moonbit
+let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::Blocking)
+```
+
+In this example, logging pressure can slow producers instead of dropping data immediately.
+
+#### When Need Bounded Async Logging With Drop Behavior
+
+When async logging should keep moving under load without blocking callers:
+```moonbit
+let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::DropNewest)
+```
+
+In this example, the incoming record is dropped if the queue cannot accept it.
+
+### Error Case
+
+e.g.:
+- If async config text uses unsupported overflow text, async config parsing raises a failure.
+
+- Under drop policies, sustained overload increases `dropped_count()` instead of guaranteeing delivery.
+
+### Notes
+
+1. This policy applies to `bitlogger_async`, not synchronous `QueuedSink`.
+
+2. Choose `Blocking` only when producer-side waiting is acceptable for the caller.

docs/api/config-error.md

@@ -0,0 +1,77 @@
+---
+name: config-error
+group: api
+category: config
+update-time: 20260613
+description: Public config parsing error alias used by synchronous config-loading helpers.
+key-word:
+    - config
+    - error
+    - alias
+    - public
+---
+
+## 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.
+
+### Interface
+
+```moonbit
+pub type ConfigError = @utils.ConfigError
+```
+
+#### output
+
+- `ConfigError` - Public config parsing error type with the case `InvalidConfig(String)`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate public wrapper.
+- 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.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Catch Config Parse Failures
+
+When raw config text should be validated before boot:
+```moonbit
+let config = parse_logger_config_text(raw) catch {
+  err if err is ConfigError => {
+    println(err.to_string())
+    return
+  }
+}
+```
+
+In this example, the caller keeps config validation failures separate from normal runtime work.
+
+#### When Need To Surface A Clear Parse Message
+
+When tooling should report why config input was rejected:
+```moonbit
+ignore(parse_logger_config_text("{bad json}")) catch {
+  err => println(err.to_string())
+}
+```
+
+In this example, the error carries a concrete message instead of failing silently.
+
+### Error Case
+
+e.g.:
+- Invalid JSON input raises `ConfigError::InvalidConfig(...)`.
+
+- Wrong field types, unsupported level text, unsupported sink kinds, or an empty `path` for a file sink also raise `ConfigError::InvalidConfig(...)`.
+
+### Notes
+
+1. This alias currently belongs to the synchronous config-loading path in `bitlogger`.
+
+2. Async config parsers in `bitlogger_async` currently raise the generic failure surface used by that package instead of `ConfigError`.

docs/api/index.md

@@ -77,6 +77,7 @@ BitLogger API navigation.
 ## Record and level
 
 - [record-new.md](./record-new.md)
+- [level.md](./level.md)
 - [level-priority.md](./level-priority.md)
 - [level-label.md](./level-label.md)
 - [level-enabled.md](./level-enabled.md)
@@ -93,6 +94,7 @@ BitLogger API navigation.
 - [split-by-level.md](./split-by-level.md)
 - [buffered-sink.md](./buffered-sink.md)
 - [queued-sink.md](./queued-sink.md)
+- [queue-overflow-policy.md](./queue-overflow-policy.md)
 - [filter-sink.md](./filter-sink.md)
 - [patch-sink.md](./patch-sink.md)
 - [file-sink.md](./file-sink.md)
@@ -130,6 +132,8 @@ BitLogger API navigation.
 
 ## Config build flow
 
+- [config-error.md](./config-error.md)
+- [sink-kind.md](./sink-kind.md)
 - [queue-config.md](./queue-config.md)
 - [queue-config-to-json.md](./queue-config-to-json.md)
 - [stringify-queue-config.md](./stringify-queue-config.md)
@@ -190,6 +194,8 @@ BitLogger API navigation.
 
 ## Async runtime and config
 
+- [async-overflow-policy.md](./async-overflow-policy.md)
+- [async-flush-policy.md](./async-flush-policy.md)
 - [async-runtime-mode.md](./async-runtime-mode.md)
 - [async-runtime-mode-label.md](./async-runtime-mode-label.md)
 - [async-runtime-supports-background-worker.md](./async-runtime-supports-background-worker.md)

docs/api/level.md

@@ -0,0 +1,70 @@
+---
+name: level
+group: api
+category: level
+update-time: 20260613
+description: Public level enum alias shared by records, filters, and logger thresholds.
+key-word:
+    - level
+    - alias
+    - severity
+    - public
+---
+
+## Level
+
+`Level` is the public severity enum used across records, filters, and logger threshold checks. It is a direct alias to the core level type, so the same five built-in variants are shared everywhere the public API accepts or returns a level.
+
+### Interface
+
+```moonbit
+pub type Level = @core.Level
+```
+
+#### output
+
+- `Level` - Public severity enum with the variants `Trace`, `Debug`, `Info`, `Warn`, and `Error`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a wrapper or a separate enum.
+- The built-in variants are `Level::Trace`, `Level::Debug`, `Level::Info`, `Level::Warn`, and `Level::Error`.
+- `Level` is used by `Record::new(...)`, logger threshold APIs, predicate helpers, and config-driven builders.
+- Ordering and display behavior come from the same underlying type, so helpers such as `priority()`, `label()`, and `enabled(...)` work on this alias unchanged.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Severity For New Records
+
+When a record should be created with a concrete severity:
+```moonbit
+let rec = Record::new(Level::Warn, "disk almost full")
+```
+
+In this example, the record uses the public `Level` alias directly.
+
+#### When Need A Threshold For Logger Filtering
+
+When a logger should only accept records at or above one severity:
+```moonbit
+let logger = Logger::new(console_sink()).with_min_level(Level::Info)
+```
+
+In this example, the same public level enum is reused as the threshold value.
+
+### Error Case
+
+e.g.:
+- `Level` itself does not have a runtime failure mode.
+
+- If external config text names an unsupported level string, parsing fails through `ConfigError` instead of producing a fallback level.
+
+### Notes
+
+1. Use `label()` for display text and `priority()` or `enabled(...)` for threshold logic.
+
+2. This alias keeps sync APIs, async APIs, and config builders on the same severity vocabulary.

docs/api/queue-overflow-policy.md

@@ -0,0 +1,70 @@
+---
+name: queue-overflow-policy
+group: api
+category: sink
+update-time: 20260613
+description: Public overflow policy alias used by synchronous queued sinks and queue config.
+key-word:
+    - queue
+    - overflow
+    - alias
+    - public
+---
+
+## 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`.
+
+### Interface
+
+```moonbit
+pub type QueueOverflowPolicy = @utils.QueueOverflowPolicy
+```
+
+#### output
+
+- `QueueOverflowPolicy` - Public synchronous queue overflow enum with the variants `DropNewest` and `DropOldest`.
+
+### Explanation
+
+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 same enum is used by code-side queue composition through `queued_sink(...)` and config-driven queue composition through `QueueConfig::new(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Bounded Queue That Prefers Older Pending Records
+
+When the oldest pending records should be preserved and new bursts can be dropped:
+```moonbit
+let sink = queued_sink(console_sink(), max_pending=32, overflow=QueueOverflowPolicy::DropNewest)
+```
+
+In this example, new records are discarded once the queue is full.
+
+#### When Need To Prefer Fresh Records Over Old Pending Work
+
+When backlog should make room for newer records:
+```moonbit
+let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
+```
+
+In this example, the oldest pending record is removed when the queue overflows.
+
+### Error Case
+
+e.g.:
+- If a queue is unbounded or never reaches capacity, the overflow policy has no effect.
+
+- If parsed JSON uses unsupported overflow text, config parsing raises `ConfigError`.
+
+### Notes
+
+1. This policy belongs to synchronous queue wrappers, not `bitlogger_async`.
+
+2. Use `AsyncOverflowPolicy` for the async logger queue behavior.

docs/api/sink-kind.md

@@ -0,0 +1,72 @@
+---
+name: sink-kind
+group: api
+category: config
+update-time: 20260613
+description: Public sink kind enum alias used by SinkConfig and config parsing.
+key-word:
+    - sink
+    - config
+    - alias
+    - public
+---
+
+## 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.
+
+### Interface
+
+```moonbit
+pub type SinkKind = @utils.SinkKind
+```
+
+#### output
+
+- `SinkKind` - Public sink selection enum with the variants `Console`, `JsonConsole`, `TextConsole`, and `File`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a wrapper or a new runtime sink implementation.
+- `SinkKind::Console` selects the basic text console sink.
+- `SinkKind::JsonConsole` selects JSON line output.
+- `SinkKind::TextConsole` selects text console output driven by `TextFormatterConfig`.
+- `SinkKind::File` selects file-backed output and requires a non-empty `path` during config parsing.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Build A File Sink Through Config
+
+When logger construction should be described entirely as config data:
+```moonbit
+let sink = SinkConfig::new(kind=SinkKind::File, path="app.log")
+let config = LoggerConfig::new(sink=sink)
+```
+
+In this example, the selected enum variant controls which built-in sink builder will be used.
+
+#### When Need Formatter-driven Console Output
+
+When the config should request text console formatting instead of the default console sink:
+```moonbit
+let sink = SinkConfig::new(kind=SinkKind::TextConsole)
+```
+
+In this example, the enum value makes the config intent explicit.
+
+### Error Case
+
+e.g.:
+- Unsupported sink kind text in parsed JSON raises `ConfigError`.
+
+- `SinkKind::File` without a non-empty `path` is rejected during config parsing.
+
+### Notes
+
+1. This enum is for config-driven sink selection, not for direct handwritten sink composition.
+
+2. Use concrete constructors such as `console_sink()` or `file_sink(...)` when building sinks in code instead of through `SinkConfig`.