log-foundry 0.10.2.dev30__tar.gz → 0.10.2.dev32__tar.gz

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev30
+Version: 0.10.2.dev32
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -862,6 +862,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
 fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/README.md

@@ -826,6 +826,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
 fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev30"
+version = "0.10.2.dev32"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/src/log_foundry/__init__.py

@@ -98,7 +98,9 @@ def health() -> Health:
       ``failed`` is an upper bound on loss rather than a count of it, since a sink that raises
       on total failure counts the attempt and hands the batch back for the worker to retry. A
       process that has never logged has no worker, and asking does not create one — the
-      snapshot is simply zeroed. Valid after :func:`shutdown`.
+      snapshot is simply zeroed, except for ``retired``, which stays truthful even for a
+      process that only ever logged outside a span and so built no worker at all (SPEC-031
+      FR-006). Valid after :func:`shutdown`.
 
     Raises:
       None.
@@ -122,6 +124,15 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     non-zero ``submitted_after_shutdown``, and the first such submission writes one stderr line
     (SPEC-030). That pair is the reading that catches the mistake above.
 
+    A process that only ever logged **outside** a span built no worker, and this used to be a
+    no-op there, leaving the sink open forever: every event lost on a sink whose ``close()`` is
+    what delivers them, the flush and the resource on a synchronous one. It now closes that
+    sink — exactly once, and without creating a worker to do it — and ``health().retired``
+    reads ``True`` afterwards rather than staying vacuously ``False`` (SPEC-031 FR-006). A
+    later level call reaches a closed sink, so a sink that guards its own post-close state
+    refuses it and one stderr line is written; a stateless one such as ``StdoutSink`` still
+    accepts it (SPEC-032).
+
     Args:
       timeout: Seconds bounding the wait for the background thread and, carved from the same
         budget, a short grace for any sink still closing after a late ``configure(sink=...)``

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/src/log_foundry/api.py

@@ -6,6 +6,7 @@ from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
 from log_foundry.context import set_baggage
+from log_foundry.decorator import _note_orphan_emit
 from log_foundry.ids import new_span_id, new_trace_id
 from log_foundry.model import Span, build_event
 
@@ -36,6 +37,21 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
     logs"). It carried a comment saying the worker "will later" own it long after the
     decision was made (SPEC-031 FR-003).
 
+    Because no worker is built here, nothing else in the library knows the sink was ever
+    written to — so this branch records it (SPEC-031 FR-006). That is what arms the exit-time
+    close for a process which only ever logs this way, and keying it on a sink this call is
+    about to write to, rather than on a *configured* sink, is deliberate: ``configure()``
+    materializes a ``StdoutSink`` whether or not anything is logged through it, and closing one
+    nothing was ever written to is cost with no benefit.
+
+    It is armed **before** the emit rather than after it, which matters for the sinks most
+    likely to need the close. SPEC-026 FR-001 makes a total failure raise, so an orphan-only
+    process against a dead syslog or HTTP destination raises on every call — and arming
+    afterwards would leave the socket that failure came from open forever, which is the leak
+    this FR exists to stop, in exactly the case that is leaking. A sink that raised is still a
+    sink that was written to. ``_ensure_sink`` is resolved first, so a sink that fails to
+    *construct* arms nothing: there is nothing to close.
+
     The orphan branch is the one that reaches the sink on the caller's own thread, with no
     worker between them to absorb a failure, so the whole branch is guarded (SPEC-025
     FR-003) — ``_ensure_sink`` constructs the sink on first use, so a sink that fails to
@@ -72,7 +88,9 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
                 start_ts=0.0,
             )
             event = build_event(orphan, level, message, fields=fields, baggage=baggage)
-            _ensure_sink().emit([event])
+            sink = _ensure_sink()
+            _note_orphan_emit()
+            sink.emit([event])
         except Exception as exc:
             _diag.absorbed("emitting an orphan log", exc, "the event was lost")
     if echo and event is not None:

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/src/log_foundry/decorator.py

@@ -32,6 +32,9 @@ __all__ = ["continue_trace", "trace"]
 _worker: Worker | None = None
 _worker_lock = threading.Lock()
 _atexit_registered = False
+_orphan_close_owed = False
+_orphan_sink_closed = False
+_orphan_retired = False
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -202,23 +205,127 @@ def _get_worker() -> Worker:
     Raises:
       Exception: Whatever constructing the sink or worker raises.
     """
-    global _worker, _atexit_registered
+    global _worker
     if _worker is None:
         with _worker_lock:
             if _worker is None:
-                if not _atexit_registered:
-                    atexit.register(_shutdown_worker)
-                    _atexit_registered = True
+                _register_exit_handler()
                 _worker = Worker(_ensure_sink())
     return _worker
 
 
+def _register_exit_handler() -> None:
+    """Registers the one ``atexit`` handler that covers both delivery paths (SPEC-031 FR-006).
+
+    One registration, not two, and one flag guarding it. :func:`_shutdown_worker` handles the
+    worker path *and* the orphan path, so an orphan log arming this does not cost a later
+    ``@trace`` its exit drain — which reusing a worker-only registration flag would. Two
+    handlers would be worse still: ``atexit`` runs LIFO, so the second would close a sink the
+    first had already closed. What is made once-only is the *close*, not the registration.
+
+    Callers hold ``_worker_lock``.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _atexit_registered
+    if not _atexit_registered:
+        atexit.register(_shutdown_worker)
+        _atexit_registered = True
+
+
+def _note_orphan_emit() -> None:
+    """Records that a level call with no span reached the sink (SPEC-031 FR-006).
+
+    This is what arms the exit-time close, and it is deliberately keyed on an event having
+    *landed* rather than on a sink existing: ``configure()`` runs ``_ensure_sink()``
+    unconditionally, so a bare ``configure(service=…)`` has already built a ``StdoutSink``,
+    and keying on that would close a sink nothing was ever written to.
+
+    The unlocked read is the fast path on a per-call route — the flag is written once and
+    never cleared, so a racing reader either sees it set or takes the lock and finds it set
+    there.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _orphan_close_owed
+    if _orphan_close_owed:
+        return
+    with _worker_lock:
+        if not _orphan_close_owed:
+            _register_exit_handler()
+            _orphan_close_owed = True
+
+
+def _close_orphan_sink() -> None:
+    """Closes a sink only the orphan path ever wrote to, once (SPEC-031 FR-006).
+
+    A process that never opens a span builds no worker, so nothing owned the sink's close and
+    nothing performed it: on a locally-buffering sink every event died in the client's batch,
+    on a synchronous one the flush and the resource were lost, and ``health()`` read all-clear
+    because every field it carries describes a worker that does not exist.
+
+    A live worker owns the close instead, and this returns — that is what makes a mixed
+    process exactly one ``close()`` in either order. It also inherits the worker's reasons for
+    *not* closing: an expired :meth:`Worker.shutdown` leaves the sink open because the drain
+    thread may still be inside ``emit``.
+
+    That check is read **under** ``_worker_lock``, not ahead of it, because :func:`_get_worker`
+    assigns ``_worker`` while holding that same lock. Unlocked, a ``shutdown()`` racing a first
+    ``@trace`` could read ``None``, block behind the worker's construction, and then close the
+    sink underneath the worker that had just captured it — reproduced with an injected
+    preemption point, the way SPEC-028 demonstrates the races that need one.
+
+    The once-only flag is set ahead of the close, as ``Worker.shutdown``'s is: a second
+    ``close()`` on a sink that partially released its resources is worse than an unclosed one.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None. This runs from ``atexit``, where an escaping exception makes CPython print a
+        traceback carrying the message arch §6 keeps out of anything the library says about
+        itself. ``Exception``, never ``BaseException`` (SPEC-025 FR-004).
+    """
+    global _orphan_sink_closed
+    with _worker_lock:
+        if _worker is not None or not _orphan_close_owed or _orphan_sink_closed:
+            return
+        _orphan_sink_closed = True
+    try:
+        _ensure_sink().close()
+    except Exception as exc:
+        _diag.absorbed("closing the sink", exc, "it may still hold its resources")
+
+
 def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
-    """Drains and closes the process worker if one was created, backing ``shutdown()``.
+    """Drains and closes the process worker, or closes an orphan-only sink, backing ``shutdown()``.
 
     The ``atexit`` registration binds this function, so the exit path gets the bounded form
     and its default (SPEC-027 FR-004) — an unbounded join in an ``atexit`` handler is a
-    process that will not exit. Idempotent.
+    process that will not exit. Idempotent on both paths.
+
+    ``_orphan_retired`` is set unconditionally and read only when there is no worker, which is
+    what makes ``health().retired`` truthful for a process that shut down without ever
+    building one (SPEC-031 FR-006). No worker is created here to answer it: standing up a
+    thread at exit to prove there is nothing to drain is pure cost, the same refusal
+    :func:`_swap_sink` and :func:`_flush_worker` already make.
 
     Args:
       timeout: Seconds to wait for the drain, or ``None`` to wait indefinitely.
@@ -229,8 +336,12 @@ def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     Raises:
       None.
     """
+    global _orphan_retired
+    _orphan_retired = True
     if _worker is not None:
         _worker.shutdown(timeout)
+        return
+    _close_orphan_sink()
 
 
 def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
@@ -301,6 +412,24 @@ def _worker_health() -> Health:
     created has not died, which is why SPEC-019 reports the terminal failure as a reason
     rather than an ``alive`` flag.
 
+    ``retired`` is the one field synthesized rather than zeroed (SPEC-031 FR-006). It records
+    an action the caller took, not a state of the worker, so it stays true in a process that
+    called ``shutdown()`` without ever building one — where it was previously vacuous, and the
+    whole snapshot read all-clear over a sink that had just been closed.
+    ``submitted_after_shutdown`` is deliberately **not** synthesized alongside it: SPEC-030
+    defines that count as submissions queued where nothing will drain them, and a later orphan
+    log is refused at the closed sink and announced instead. The two are not the same claim.
+
+    The synthesis also survives a worker built *after* that shutdown, which is why it is an
+    ``or`` rather than a fallback. An orphan-only ``shutdown()`` leaves ``_worker`` unset, so a
+    later ``@trace`` constructs a fresh worker whose own ``retired`` is ``False`` — and reading
+    that alone would say the process was never shut down, contradicting this function's own
+    guarantee one call earlier. The events that worker carries are not lost silently: against a
+    sink that guards its post-close state they raise and land in ``failed_batches`` (measured),
+    and against one that releases nothing on ``close()`` they genuinely still deliver. So the
+    detection is ``failed_batches`` there rather than SPEC-030's ``retired`` +
+    ``submitted_after_shutdown`` pair, which stays the signal for the path it was built for.
+
     Args:
       None.
 
@@ -312,8 +441,11 @@ def _worker_health() -> Health:
     """
     worker = _worker
     if worker is None:
-        return Health(queued=0, dropped=0, failed_batches=0)
-    return worker.health()
+        return Health(queued=0, dropped=0, failed_batches=0, retired=_orphan_retired)
+    health = worker.health()
+    if _orphan_retired and not health.retired:
+        return health._replace(retired=True)
+    return health
 
 
 def _flush(span: Span) -> None:

{log_foundry-0.10.2.dev30 → log_foundry-0.10.2.dev32}/src/log_foundry/worker.py

@@ -76,8 +76,10 @@ class Health(NamedTuple):
 
     Attributes:
       queued: Submissions currently buffered. Approximate by nature: it is read without
-        stopping the world, and briefly counts the internal flush/shutdown markers alongside
-        real submissions.
+        stopping the world, and counts the internal flush/shutdown markers alongside real
+        submissions — normally only in passing, but a ``flush()`` marker stranded by racing
+        ``shutdown()`` is answered and then counted for the life of the process, since
+        ``Queue`` offers no way to remove one specific item.
       dropped: Submissions discarded because the queue was full (backpressure).
       failed_batches: Batches abandoned after the retry budget was spent.
       stopped_reason: The exception type name that terminated the drain thread, or ``None`` if
@@ -90,12 +92,15 @@ class Health(NamedTuple):
         the sink reports nothing (SPEC-026 FR-003). Nested rather than folded into the
         integers above because they count different things: ``dropped`` here is backpressure
         at this queue, ``dropped`` on the sink is an event that never reached the wire.
-      retired: Whether :meth:`Worker.shutdown` has been called. It describes an action the
+      retired: Whether ``shutdown()`` has been called. It describes an action the
         caller took, not a failure the library detected, which is why it is a boolean where
         ``stopped_reason`` is a string — SPEC-019 rejected an ``alive`` flag because it would
         read ``False`` for a process that never logged, and that objection does not apply to a
         field which is simply ``False`` until someone calls ``shutdown()`` (SPEC-030 FR-001).
         On its own it is not a fault: a process that shuts down and stops logging is correct.
+        It is the one field ``decorator._worker_health`` synthesizes rather than zeroing, so
+        that a process which only ever logged outside a span — and therefore has no worker at
+        all — still reports its own shutdown truthfully (SPEC-031 FR-006).
       submitted_after_shutdown: Submissions accepted after ``shutdown()`` and queued where
         nothing will drain them. Non-zero alongside ``retired`` is the signature of the
         serverless mistake — ``shutdown()`` called per invocation on a warm container, so the
@@ -224,6 +229,7 @@ class Worker:
         self._closers: list[threading.Thread] = []
         self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
         self._stop = threading.Event()
+        self._drain_finished = threading.Event()
         self._shutdown_done = False
         self._sink_closed = False
         self._lock = threading.Lock()
@@ -335,8 +341,11 @@ class Worker:
         """Snapshots the delivery counters (SPEC-017 FR-005, SPEC-019 FR-003).
 
         This stays valid after :meth:`shutdown`: the counters are plain integers that outlive
-        the thread, and the final drain consumes the queue, so ``queued`` reads 0 rather than a
-        stale marker. The same applies to ``stopped_reason``, since a caller finding a dead
+        the thread, and the final drain consumes the queue. ``queued`` therefore reads 0 for a
+        worker nothing logged to afterwards — but not always: submissions accepted after the
+        shutdown stay queued on purpose (SPEC-030), and a ``flush()`` marker stranded by
+        racing it is answered and then counted, as ``Health.queued`` records. The same applies
+        to ``stopped_reason``, since a caller finding a dead
         worker will usually call ``shutdown()`` next. Reading it after a shutdown is in fact
         the point of ``retired`` and ``submitted_after_shutdown`` (SPEC-030 FR-001), which
         report a state only a retired worker can be in.
@@ -405,6 +414,24 @@ class Worker:
         queue ``put_nowait`` would skip the flush and return as though it had succeeded, the
         one outcome a flush must never produce silently.
 
+        The drain's completion is re-checked **after** the put, and that second look is what
+        makes a ``timeout=None`` call safe. The checks above can both pass microseconds before
+        the drain finishes, leaving this marker queued behind something that will never read it
+        — a bounded caller then waits out its timeout, which SPEC-021 accepts as correct either
+        way, but an unbounded one waits forever.
+
+        It tests ``_drain_finished`` and not only ``is_alive()``, because the two are not the
+        same instant and the gap between them is where the hang survives: the terminal-failure
+        path sweeps for markers and *then* returns, so a marker queued after that sweep sits
+        behind a thread still reading as alive. The flag is set **before** the sweep, and a
+        ``put`` and the sweep's snapshot both take the queue's own mutex, so a marker either
+        lands before the snapshot and is answered, or lands after it and finds the flag set.
+
+        Reporting is by the **marker**, never by the check alone. A drain that answered this
+        marker and then exited has delivered, and saying otherwise would be a false failure —
+        one ``swap_sink`` reads as an unconfirmed drain, counting ``incomplete_swaps``, leaving
+        the previous sink open and writing a loss line for a swap that in fact completed.
+
         Args:
           timeout: Seconds bounding the whole call — one deadline shared by the put and the
             wait, so the two cannot add up to twice the timeout. ``None`` waits indefinitely.
@@ -430,6 +457,8 @@ class Worker:
             self._queue.put(marker, timeout=timeout)
         except queue.Full:
             return False
+        if self._drain_finished.is_set() or not self._thread.is_alive():
+            return marker.event.is_set() and marker.delivered
         remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
         if not marker.event.wait(remaining):
             return False
@@ -635,6 +664,36 @@ class Worker:
         ``close()`` twice on a sink that may have partially released its resources; what
         SPEC-025 FR-004 changed is that the failure is announced rather than swallowed.
 
+        **The sentinel is queued before ``_stop`` is set, and while the drain loop is running
+        that order is what makes it impossible to strand.** Both ways of leaving the loop —
+        taking the sentinel, or seeing ``_stop`` — can only happen once it is already in the
+        queue, so either that ``get`` consumes it or :meth:`_final_drain` does. The reverse
+        order left a window in which the loop read ``_stop``, exited, and finished its final
+        drain before the sentinel landed. It never lost an event, but left ``health().queued``
+        reading 1 for the life of the process. The rate is load-dependent and not worth
+        quoting as a property — rare when idle, and repeatedly reproduced between roughly one
+        shutdown in 14 and one in 50 with spinner threads and a tightened switch interval.
+
+        Paying for that order needs :meth:`_drain` to break on the sentinel rather than loop, or
+        a thread taking it before ``_stop`` was set would block for another ``flush_interval``
+        — measured stalling low single-digit percentages of shutdowns under load for the entire
+        budget, latching a ``stopped_reason`` of ``"ShutdownTimeout"``, which is far worse than
+        the cosmetic problem being fixed.
+
+        The premise is the loop, so the put is skipped once the drain has stopped reading. A
+        drain that died terminally (SPEC-019) is not coming back for a wake-up, and queueing one
+        for it would strand it permanently — reintroducing the symptom on the one path the
+        ordering cannot reach. The gate is ``_drain_finished`` rather than ``is_alive()``,
+        because they are not the same instant: the thread is still alive throughout
+        :meth:`_terminal_failure`, which writes to stderr and can block on a slow reader, and a
+        liveness test would queue a sentinel through that whole window. The flag is set before
+        that call, so this one does not.
+
+        :meth:`_release_waiters` runs on the way out for the sibling case the ordering cannot
+        reach: a ``flush()`` that passed its liveness check microseconds before the thread
+        finished can still queue a marker nothing will answer, and with ``timeout=None`` that
+        caller waits forever rather than merely too long.
+
         The worker does not come back, and :meth:`submit` keeps accepting afterwards — so a
         caller that logs again queues events nothing will drain. That is reported rather than
         prevented, through ``retired`` and ``submitted_after_shutdown`` (SPEC-030 FR-001) and
@@ -661,11 +720,12 @@ class Worker:
             self._close_if_owed()
             self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
             return
+        if not self._drain_finished.is_set():
+            try:
+                self._queue.put_nowait(_SHUTDOWN)
+            except queue.Full:
+                pass
         self._stop.set()
-        try:
-            self._queue.put_nowait(_SHUTDOWN)
-        except queue.Full:
-            pass
         self._thread.join(timeout)
         if self._thread.is_alive():
             queued = self._queued_or_unknown()
@@ -679,6 +739,7 @@ class Worker:
                 f"because the worker thread is still using it",
             )
             return
+        self._release_waiters()
         self._close_if_owed()
         self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
 
@@ -823,6 +884,18 @@ class Worker:
         ``BaseException``. It records and exits; looping onward past a ``KeyboardInterrupt``
         would be a worse failure than the one this prevents.
 
+        The two ``finally`` blocks are nested rather than merged, and the order they impose is
+        load-bearing twice over. ``_drain_finished`` is set the instant the loop stops reading
+        the queue — *before* :meth:`_terminal_failure`, which writes to stderr and can block on
+        a slow reader — so a ``shutdown()`` arriving during that window sees a drain that is
+        already finished and declines to queue a sentinel nothing would consume. And it is set
+        before :meth:`_release_waiters`, so a marker either lands ahead of that sweep's snapshot
+        and is answered by it, or lands behind it and finds the flag set; both take the queue's
+        own mutex, which is what leaves no gap between the two. Sweeping here rather than only
+        in :meth:`Worker.shutdown` is what covers the paths ``shutdown`` never reaches — a
+        terminal failure, and a bounded shutdown that expired while this thread was still
+        inside an emit.
+
         Args:
           None.
 
@@ -834,9 +907,13 @@ class Worker:
         """
         pending: list[list[dict[str, object]]] = []
         try:
-            self._drain(pending)
+            try:
+                self._drain(pending)
+            finally:
+                self._drain_finished.set()
         except BaseException as exc:
             self._terminal_failure(exc, len(pending))
+        finally:
             self._release_waiters()
 
     def _release_waiters(self) -> None:
@@ -849,10 +926,20 @@ class Worker:
         ``health().queued`` and the terminal line report; each keeps its pessimistic
         ``delivered``, which is the truth here.
 
+        It is called from two places. The terminal-failure path is the original one. The clean
+        :meth:`shutdown` path was added because that same enqueue-after-the-drain race happens
+        there too, and hurts more: measured stranding a marker in 13 of 400 shutdowns raced
+        against a ``flush()`` under load, where the caller sat out its whole timeout — and
+        ``flush(timeout=None)``, which the API documents as supported, waits forever rather
+        than too long. The marker keeps its pessimistic ``delivered``, which is the honest
+        answer: the drain that would have carried it is gone.
+
         One residual race, stated rather than papered over: a ``flush()`` that passed its
-        liveness check microseconds before the thread died can still enqueue a marker after
-        this sweep, and that one waits out its timeout — then returns False, which is correct
-        either way.
+        liveness check microseconds before *this* sweep can still enqueue a marker after it,
+        and that one waits out its timeout — then returns False, which is correct either way.
+        A marker left queued is also still counted by ``health().queued``, which describes
+        submissions; removing it would mean deleting a specific item, which ``Queue`` has no
+        public way to do, and the read above is the access ``architecture.md`` §13 sanctions.
 
         The reliance on ``queue.Queue``'s private ``mutex`` and ``queue`` is deliberate and is
         recorded in ``architecture.md`` §13 Known Constraints (SPEC-031 FR-005): there is no
@@ -925,6 +1012,13 @@ class Worker:
         advanced even when idle: otherwise the timeout collapses to zero and ``get`` busy-spins
         a core.
 
+        The shutdown sentinel **breaks** rather than falling through to the loop condition.
+        :meth:`shutdown` queues it before setting ``_stop``, so a thread that takes it may find
+        ``_stop`` still clear; continuing would re-enter ``get`` and block for another
+        ``flush_interval``, which is a slow shutdown rather than a prompt one. Leaving
+        immediately is safe because the only thing after the loop is :meth:`_final_drain`, which
+        collects whatever is still queued — the sentinel is a wake-up, never a fence.
+
         Args:
           pending: The accumulator owned by :meth:`_run`, which reports its size on a terminal
             failure. It is mutated in place rather than rebound, so that count is accurate.
@@ -950,7 +1044,9 @@ class Worker:
                     last_flush = time.monotonic()
                     item.event.set()
                 continue
-            if item is not None and item is not _SHUTDOWN:
+            if item is _SHUTDOWN:
+                break
+            if item is not None:
                 pending.append(cast("list[dict[str, object]]", item))
             now = time.monotonic()
             if len(pending) >= self.batch_size or now - last_flush >= self.flush_interval: