📝 clarify async lifecycle docs

docs/api/async-logger-run.md

@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-run
 
-Start the async logger worker loop. This is the core runtime API that drains queued records to the underlying sink and updates worker lifecycle state.
+Start the async logger worker loop. This is the core runtime API that drains queued records to the underlying sink and updates worker lifecycle state around that drain loop.
 
 ### Interface
 
@@ -33,12 +33,12 @@ pub async fn[S : @bitlogger.Sink] AsyncLogger::run(self : AsyncLogger[S]) -> Uni
 
 Detailed rules explaining key parameters and behaviors
 
-- `run()` sets `is_running` to `true` while the worker loop is active.
-- It clears previous failure state before worker execution begins.
-- It also resets `last_error()` to an empty string before worker execution begins.
-- On failure, the logger records `has_failed=true` and stores the error text in `last_error`.
-- On failure, `is_running` is cleared before the error is raised back out of `run()`.
-- The worker exits when the queue is closed or when a failure aborts processing.
+- `run()` sets `is_running` to `true` before worker execution begins.
+- Every invocation clears previous failure state first by setting `has_failed=false` and `last_error()` to an empty string.
+- The method then keeps draining records until `queue.get()` stops with `AsyncLoggerClosed` or a worker error escapes.
+- On a normal queue-close exit, `run()` clears `is_running` and returns normally.
+- On failure, the logger records `has_failed=true`, stores the error text in `last_error`, clears `is_running`, and then raises the error back out of `run()`.
+- This helper does not enforce a single-worker guard by itself, so the public contract should be treated as application-controlled worker startup rather than an API that deduplicates repeated `run()` calls.
 
 ### How to Use
 
@@ -70,12 +70,14 @@ In this example, the application decides when the worker begins instead of hidin
 ### Error Case
 
 e.g.:
-- If the worker loop fails, `has_failed()` becomes `true` and `last_error()` stores the error text.
+- If the worker loop fails, `has_failed()` becomes `true`, `last_error()` stores the error text, and `run()` raises that failure to the caller.
 
 - If `run()` is never started, accepted records may remain queued and not reach the sink.
 
 - A later `run()` attempt starts from a fresh failure flag and empty `last_error()` string, even if an earlier run failed.
 
+- Starting more than one `run()` task for the same logger is not prevented by this method and can produce application-level worker coordination bugs.
+
 ### Notes
 
 1. `async_logger(...)` only constructs the logger; `run()` is what activates queue draining.
@@ -83,3 +85,5 @@ e.g.:
 2. Pair this API with `shutdown()` for a complete worker lifecycle.
 
 3. Pair it with `has_failed()`, `last_error()`, or `state()` when tests need to inspect how a worker exit affected logger health.
+
+4. Start one deliberate worker task per logger unless your own code is intentionally coordinating a different pattern.