log-foundry 0.7.1.dev3__tar.gz → 0.7.2.dev4__tar.gz

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.7.1.dev3
+Version: 0.7.2.dev4
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -681,9 +681,19 @@ lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
 explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
 end of a short script. It is idempotent.
 
-`flush(timeout=5.0)` returns `True` when every event submitted before the call has been passed
-to the sink, and `False` if that did not happen within `timeout` (or the worker was already shut
-down). It never raises — a logging call must not be the reason your function fails. Passing
+`flush(timeout=5.0)` returns `True` when **nothing was lost while the call was outstanding** — the
+drain it forces reached the sink, and so did anything else the worker emitted while it waited its
+turn. It returns `False` on timeout, when the worker was already shut down or has died, and when
+any batch was abandoned inside that window. A `True` is evidence of delivery, not merely that a
+drain took place.
+
+The window starts when you call it. A batch abandoned *before* that is deliberately not its
+business: the loss is already counted in `health().failed_batches` and reported on stderr, and
+folding it in would make every later `flush()` in the process report a failure it did not incur.
+So `flush()` answers "did the logs I am waiting on get out", and `health()` answers "has anything
+been lost at all" — **check both**, as the handler below does.
+
+It never raises — a logging call must not be the reason your function fails. Passing
 `timeout=None` waits indefinitely, which is unsafe anywhere with an execution deadline.
 
 #### Serverless / short-lived processes
@@ -715,9 +725,17 @@ def handler(event, context):
     try:
         return do_work(event)
     finally:
-        lf.flush()      # in `finally`: the failed invocation is the one worth logging.
-                        # NEVER shutdown() here — the worker does not come back, and every
-                        # later invocation on this warm container would log nothing.
+        # In `finally`: the failed invocation is the one worth logging. NEVER shutdown() here —
+        # the worker does not come back, and every later invocation on this warm container
+        # would log nothing.
+        drained = lf.flush()
+        h = lf.health()
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+            # `drained` covers this invocation's tail; the counters cover anything the worker
+            # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # Emitting this through your platform's own logger keeps it outside the pipeline
+            # that just failed.
+            print(f"log-foundry: undelivered logs ({drained=}, {h=})")
 ```
 
 By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
@@ -765,6 +783,12 @@ the default configuration the interpreter's limit — not `max_value_bytes` —
 unlikely to meet it deliberately; `int.from_bytes(blob, "big")` over a couple of kilobytes gets
 there. Any ceiling firing sets `truncated: true` on the event.
 
+`max_value_bytes` therefore carries two units: **UTF-8 bytes** for a string, **rendered decimal
+length** (sign included) for an integer. They coincide for ASCII digits, and one ceiling for "how
+big may a single value get" was preferred to a second config key. Note that all four ceilings
+bound each *value* — an event of many bounded values can still be large; see
+[Known constraints](docs/architecture.md#known-constraints).
+
 ## Development
 
 ```bash

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/README.md

@@ -645,9 +645,19 @@ lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
 explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
 end of a short script. It is idempotent.
 
-`flush(timeout=5.0)` returns `True` when every event submitted before the call has been passed
-to the sink, and `False` if that did not happen within `timeout` (or the worker was already shut
-down). It never raises — a logging call must not be the reason your function fails. Passing
+`flush(timeout=5.0)` returns `True` when **nothing was lost while the call was outstanding** — the
+drain it forces reached the sink, and so did anything else the worker emitted while it waited its
+turn. It returns `False` on timeout, when the worker was already shut down or has died, and when
+any batch was abandoned inside that window. A `True` is evidence of delivery, not merely that a
+drain took place.
+
+The window starts when you call it. A batch abandoned *before* that is deliberately not its
+business: the loss is already counted in `health().failed_batches` and reported on stderr, and
+folding it in would make every later `flush()` in the process report a failure it did not incur.
+So `flush()` answers "did the logs I am waiting on get out", and `health()` answers "has anything
+been lost at all" — **check both**, as the handler below does.
+
+It never raises — a logging call must not be the reason your function fails. Passing
 `timeout=None` waits indefinitely, which is unsafe anywhere with an execution deadline.
 
 #### Serverless / short-lived processes
@@ -679,9 +689,17 @@ def handler(event, context):
     try:
         return do_work(event)
     finally:
-        lf.flush()      # in `finally`: the failed invocation is the one worth logging.
-                        # NEVER shutdown() here — the worker does not come back, and every
-                        # later invocation on this warm container would log nothing.
+        # In `finally`: the failed invocation is the one worth logging. NEVER shutdown() here —
+        # the worker does not come back, and every later invocation on this warm container
+        # would log nothing.
+        drained = lf.flush()
+        h = lf.health()
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+            # `drained` covers this invocation's tail; the counters cover anything the worker
+            # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # Emitting this through your platform's own logger keeps it outside the pipeline
+            # that just failed.
+            print(f"log-foundry: undelivered logs ({drained=}, {h=})")
 ```
 
 By default each invocation is its own trace, so N invocations produce N `trace_id`s. To join
@@ -729,6 +747,12 @@ the default configuration the interpreter's limit — not `max_value_bytes` —
 unlikely to meet it deliberately; `int.from_bytes(blob, "big")` over a couple of kilobytes gets
 there. Any ceiling firing sets `truncated: true` on the event.
 
+`max_value_bytes` therefore carries two units: **UTF-8 bytes** for a string, **rendered decimal
+length** (sign included) for an integer. They coincide for ASCII digits, and one ceiling for "how
+big may a single value get" was preferred to a second config key. Note that all four ceilings
+bound each *value* — an event of many bounded values can still be large; see
+[Known constraints](docs/architecture.md#known-constraints).
+
 ## Development
 
 ```bash

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.7.1.dev3"
+version = "0.7.2.dev4"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.34"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink
@@ -58,6 +58,7 @@ exclude = [
 
 # Development-only dependencies (not shipped to consumers).
 # Install with: poetry install --with dev
+
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.0"
 pytest-asyncio = "^1.4.0"        # for testing async @trace (guide Phase 8)

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/src/log_foundry/__init__.py

@@ -30,10 +30,11 @@ except PackageNotFoundError:  # running from a source tree that isn't installed
 def flush(timeout: float | None = 5.0) -> bool:
     """Drain buffered events through the sink without closing it.
 
-    Every event submitted before this call has been passed to ``sink.emit`` when it returns
-    ``True``. (Events submitted concurrently by another thread may or may not be included —
-    the caller cannot have meant those.) Unlike :func:`shutdown` the background worker stays
-    alive and the sink stays open, so logging continues normally afterwards.
+    ``True`` means the events submitted before this call reached the sink; ``False`` means the
+    drain carrying them was abandoned, or never completed. (Events submitted concurrently by
+    another thread may or may not be included — the caller cannot have meant those.) Unlike
+    :func:`shutdown` the background worker stays alive and the sink stays open, so logging
+    continues normally afterwards.
 
     This is the drain for a process that is *frozen* rather than exited — an AWS Lambda
     handler must drain before it returns, but will be invoked again on the same warm
@@ -42,8 +43,11 @@ def flush(timeout: float | None = 5.0) -> bool:
     ``timeout=None`` waits indefinitely, which is unsafe in any environment with an execution
     deadline — it converts "some logs were lost" into "the invocation timed out".
 
-    Returns ``False`` if the drain did not complete within ``timeout``, or if the worker has
-    already been shut down. Never raises.
+    Returns ``False`` if the drain did not complete within ``timeout``, if the worker has
+    already been shut down or has died, or if a batch was abandoned while this call was
+    outstanding (SPEC-021 FR-001) — a ``True`` means the events were delivered, not merely that
+    a drain took place. A batch lost *before* the call is outside this call's window and belongs
+    to :func:`health`, whose ``failed_batches`` is the cumulative record. Never raises.
     """
     from log_foundry.decorator import _flush_worker
 

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/src/log_foundry/config.py

@@ -24,6 +24,15 @@ class Config:
     The four ``max_*`` ceilings bound every event payload (SPEC-017 FR-002). Defaults are set so
     that the overwhelming majority of events are untouched; they exist to stop *one* pathological
     value getting a whole event rejected by a sink's hard limit.
+
+    ``max_value_bytes`` carries **two units**, deliberately (SPEC-020, recorded by SPEC-021): a
+    string is measured in UTF-8 bytes, an integer in the decimal length it renders as, sign
+    included. They coincide for ASCII digits, and one ceiling covering "how big may a single
+    value get" beat a second config key for a distinction almost no one configures. An integer is
+    also bounded by ``sys.get_int_max_str_digits()`` whenever that is lower, since a longer one
+    cannot be rendered at all.
+
+    They bound each *value*, not the event as a whole — see arch §13 Known Constraints.
     """
 
     service: str = "unknown"
@@ -31,7 +40,7 @@ class Config:
     env: str = "dev"
     sink: Sink | None = None
     defaults: dict[str, object] = field(default_factory=dict)
-    max_value_bytes: int = 8192  # per str value, UTF-8 bytes
+    max_value_bytes: int = 8192  # per value: UTF-8 bytes for a str, rendered digits for an int
     max_stack_bytes: int = 32768  # error.stack only — legitimately long, and worth keeping
     max_keys: int = 256  # per mapping / sequence
     max_depth: int = 8  # nesting levels

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/src/log_foundry/sanitize.py

@@ -55,6 +55,12 @@ _DEPTH_LIMIT = "<depth limit>"
 _LOG10_2_NUM = 30103
 _LOG10_2_DEN = 100000
 
+# ``int.__lt__`` bound once, for the sign test in :meth:`_Coercer.integer` (SPEC-021 FR-003). The
+# unbound slot cannot be diverted by an ``int`` subclass the way ``value < 0`` can, but reaching
+# it through ``int.__lt__`` costs a global plus an attribute lookup on a per-value hot path;
+# binding it here recovers about a third of that, the same idiom as the constants above.
+_INT_LT = int.__lt__
+
 # Exact-type membership, deliberately not ``isinstance``. ``IntEnum``/``StrEnum`` members *are*
 # ``int``/``str`` instances, so an isinstance check would pass the enum member itself through and
 # hand a sink an ``Enum`` where a plain value was promised. Exact typing lets them fall to the
@@ -74,6 +80,11 @@ def _int_digit_ceiling(max_value_bytes: int) -> int:
     raises ``ValueError``, which ``json.dumps`` inherits. A configured ceiling above that cannot be
     honoured — rendering such an integer is the very thing that raises — so the interpreter's limit
     wins whenever it is lower. A limit of ``0`` means the interpreter imposes none.
+
+    The caller measures a negative value's rendered length, sign included, against this; the
+    interpreter's own limit counts digits only. A negative integer sitting exactly on the
+    interpreter bound is therefore replaced rather than rendered — one value at the far edge, in
+    the direction this module always errs (SPEC-021 FR-003).
     """
     limit = sys.get_int_max_str_digits()
     return max_value_bytes if limit <= 0 else min(max_value_bytes, limit)
@@ -278,7 +289,11 @@ class _Coercer:
         The size test is ``bit_length()``, never ``len(str(value))``: converting an over-long
         integer to a string raises the very ``ValueError`` this bound exists to prevent, so the
         obvious check would move the crash rather than remove it (FR-002). ``bit_length()`` is
-        O(1), total, and ignores the sign, so ``n`` and ``-n`` are bounded identically.
+        O(1), total, and ignores the sign — so the minus sign is added back explicitly, since the
+        ceiling measures what the value *renders* as and ``-10**9`` renders as eleven bytes
+        (SPEC-021 FR-003). The placeholder still names the digit count: a sign is not a digit.
+        The sign is read through an *unbound* ``int.__lt__``, which an ``int`` subclass cannot
+        divert; ``bit_length()`` stays the one trusted call, as below.
 
         An over-long integer is *replaced*, not clipped. Dropping digits would silently change the
         value, and a wrong number is worse than a visibly elided one — so this reuses the
@@ -291,7 +306,13 @@ class _Coercer:
         ``type()`` check to catch only a value engineered to lie about itself.
         """
         digits = value.bit_length() * _LOG10_2_NUM // _LOG10_2_DEN + 1
-        if digits <= _int_digit_ceiling(self._cfg.max_value_bytes):
+        # ``_INT_LT`` (unbound ``int.__lt__``), never ``value < 0``: on an ``int`` *subclass* the
+        # operator dispatches to user code, which can raise — and a raise here is caught up in
+        # :meth:`value`, replacing the whole enclosing mapping and taking every sibling key with
+        # it, which is precisely what :meth:`key` was written to prevent. The unbound call reads
+        # the underlying integer and cannot be overridden.
+        rendered = digits + 1 if _INT_LT(value, 0) else digits
+        if rendered <= _int_digit_ceiling(self._cfg.max_value_bytes):
             return value
         self.truncated = True
         return f"<int: ~{digits} digits>"

{log_foundry-0.7.1.dev3 → log_foundry-0.7.2.dev4}/src/log_foundry/worker.py

@@ -74,12 +74,41 @@ class _FlushMarker:
 
     Like ``_SHUTDOWN`` it is never emitted — but unlike ``_SHUTDOWN`` it carries state, so it is
     a class rather than a bare sentinel object.
+
+    ``delivered`` carries the drain's *outcome* back to the waiter, not merely the fact that the
+    marker was reached (SPEC-021 FR-001). It is written by the drain thread before ``event.set()``
+    and read by the waiter after ``event.wait()`` returns, so the ``Event`` supplies the ordering
+    and no further lock is needed.
+
+    The outcome is computed from ``seen_failures`` — ``Worker.failed_batches`` as it stood when
+    this marker was created, on the *caller's* thread — against the same counter when the marker is
+    answered. Equal means nothing was abandoned while this flush was outstanding, which covers both
+    the batch the marker forces and any batch another flush or a batching trigger emitted in the
+    meantime. So every flush *outstanding* when a batch is abandoned reports it, including the ones
+    whose own emit found nothing left to do because another marker's emit had just cleared and lost
+    it — that case was the original false success.
+
+    Two limits, both deliberate. A batch abandoned *before* the call is not in scope: that loss is
+    already in ``failed_batches`` and on stderr, and folding it in would make every later empty
+    flush report a failure it did not incur. It follows that two *concurrent* flushes need not
+    agree — one stamped before the abandonment and one after are the outstanding case and the
+    already-lost case respectively, and the race between them decides which is which. Reporting a
+    past loss and not letting a past loss stick are the same property read in opposite directions;
+    FR-001's "an empty drain is a successful one" chooses. ``health().failed_batches`` is what
+    reports a loss regardless of when anyone asked.
+
+    ``delivered`` starts ``False``: every path that answers a marker assigns it explicitly, so the
+    default is read only when the drain thread died without computing an answer, where "I could not
+    establish that this was delivered" is the honest reading. (The spec's Data Model sketched the
+    default as ``True``, before the concurrent-flush case moved the empty-drain answer off it.)
     """
 
-    __slots__ = ("event",)
+    __slots__ = ("delivered", "event", "seen_failures")
 
-    def __init__(self) -> None:
+    def __init__(self, seen_failures: int) -> None:
         self.event = threading.Event()
+        self.delivered = False
+        self.seen_failures = seen_failures
 
 
 class Worker:
@@ -162,10 +191,24 @@ class Worker:
     def flush(self, timeout: float | None = 5.0) -> bool:
         """Drain everything submitted before this call through the sink, without stopping.
 
-        Returns ``True`` once the worker has emitted them, ``False`` on timeout or when the
-        worker has already been shut down. Unlike :meth:`shutdown` the thread keeps running, the
-        sink is **not** closed, and the once-only shutdown flag is untouched, so logging
-        continues normally afterwards (SPEC-013 FR-002).
+        Returns ``True`` once the worker has *delivered* them — ``False`` on timeout, on a worker
+        already shut down or dead, on a queue too full to accept the marker, and when the drain
+        carrying those events was abandoned after exhausting retries (SPEC-021 FR-001). That last
+        case used to return ``True``: the drain had run, so the marker was answered regardless of
+        what came of the emit. It is a false success exactly where ``flush()`` matters most — a
+        serverless handler draining before the environment freezes has the return value as its
+        only evidence the tail of the queue survived.
+
+        The precise claim is *nothing was abandoned while this call was outstanding*: the batch
+        this flush forces, and any batch another flush or a batching trigger emitted while its
+        marker waited its turn. A batch abandoned **before** the call is not in scope — that loss
+        is already in ``failed_batches`` and on stderr, and counting it here would make every
+        later empty flush report a failure it did not incur. ``health()`` is the cumulative
+        record; this is a verdict on one drain.
+
+        Unlike :meth:`shutdown` the thread keeps running, the sink is **not** closed, and the
+        once-only shutdown flag is untouched, so logging continues normally afterwards
+        (SPEC-013 FR-002).
         """
         with self._lock:
             if self._shutdown_done:
@@ -175,7 +218,12 @@ class Worker:
                 return False
         if not self._thread.is_alive():
             return False
-        marker = _FlushMarker()
+        with self._lock:
+            # Stamped here, on the caller's thread, *before* the marker joins the queue: it is the
+            # baseline the drain thread compares against, so anything abandoned from this moment
+            # on is attributed to this flush. Reading it after the put would race the very emit
+            # the flush is about to force.
+            marker = _FlushMarker(self.failed_batches)
         # One deadline shared by the put and the wait: a caller asked for a bound on the whole
         # call, not on each half of it, so the two cannot add up to 2 * timeout.
         deadline = None if timeout is None else time.monotonic() + timeout
@@ -187,7 +235,9 @@ class Worker:
         except queue.Full:
             return False
         remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
-        return marker.event.wait(remaining)
+        if not marker.event.wait(remaining):
+            return False  # timed out: the drain never happened, so it delivered nothing.
+        return marker.delivered
 
     def shutdown(self) -> None:
         """Stop the thread, drain + emit everything queued, then ``close()`` the sink.
@@ -224,6 +274,31 @@ class Worker:
             self._drain(pending)
         except BaseException as exc:  # deliberately broad — see the docstring
             self._terminal_failure(exc, len(pending))
+            self._release_waiters()
+
+    def _release_waiters(self) -> None:
+        """Answer every ``flush()`` marker still queued, so no caller waits out its timeout.
+
+        A ``BaseException`` from the main loop skips ``_final_drain`` entirely, which is where
+        queued markers are normally answered — leaving a waiter to sit for its full ``timeout``
+        on a thread that is never coming back. FR-001 requires the waiter to be released on every
+        path, and this is the last one.
+
+        The markers are *read* out of the queue rather than consumed: the queued event-lists are
+        the evidence ``health().queued`` and the terminal line report, and answering a waiter must
+        not erase it. Each keeps its pessimistic ``delivered``, which is the truth here.
+
+        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 — and then returns ``False``, which is correct either way.
+        """
+        try:
+            with self._queue.mutex:  # a snapshot, so a marker cannot be missed mid-iteration
+                markers = [i for i in self._queue.queue if isinstance(i, _FlushMarker)]
+            for marker in markers:
+                marker.event.set()
+        except Exception:  # this runs *after* the record and the stderr line; neither may be lost
+            pass
 
     def _terminal_failure(self, exc: BaseException, undrained: int) -> None:
         """Record the drain loop's terminal exit, then announce it (FR-001, FR-002).
@@ -233,14 +308,30 @@ class Worker:
         must not be able to ride on it. The exception's *type* is reported and its message is
         not — a sink's exception text can carry event data, and arch §6 keeps caller data out of
         places it was not asked for (the same rule behind ``sanitize``'s type-name placeholder).
+
+        The count reports what was *in hand* and what was still *queued behind it* (SPEC-021
+        FR-002). Held alone under-reads the loss: nothing will drain the queue either, so an
+        operator reading "1 undrained event-list(s)" could conclude far less was lost than was.
+
+        The queued figure is "items", not "event-lists", and says so: like ``Health.queued`` it is
+        read without stopping the world, so it counts any internal flush/shutdown marker sitting
+        alongside real submissions, and a producer thread can add to the queue between the death
+        and the read. It is a floor on what was lost, which is the useful direction.
         """
         name = type(exc).__name__
         with self._lock:
             self.stopped_reason = name
+        try:
+            # In its own guard, and after the record: ``qsize()`` is not guaranteed on every
+            # platform's queue, and a diagnostic must not be the reason the diagnosis is lost.
+            queued: object = self._queue.qsize()
+        except Exception:
+            queued = "?"
         try:
             sys.stderr.write(
                 f"log-foundry: worker thread stopped on {name}; {undrained} undrained "
-                f"event-list(s), nothing further will be delivered\n"
+                f"event-list(s) held and {queued} queued item(s) undelivered, nothing further "
+                f"will be delivered\n"
             )
         except Exception:  # best-effort: the record above is what an operator reads.
             pass
@@ -265,12 +356,13 @@ class Worker:
                 # marker must never fall through to the append below, where it would be treated
                 # as a list of events and handed to sink.emit, killing this thread.
                 try:
-                    if pending:
-                        self._emit(pending)
-                        pending.clear()
+                    self._emit_pending(pending)
+                    item.delivered = self._nothing_lost_since(item)
                 finally:
                     # Signal even if the emit died, so a waiter is released rather than left to
-                    # wait out its timeout on a thread that is no longer running.
+                    # wait out its timeout on a thread that is no longer running. A failing flush
+                    # therefore returns False promptly rather than at the caller's timeout, and
+                    # an emit that died leaves the marker's pessimistic default standing.
                     last_flush = time.monotonic()
                     item.event.set()
                 continue
@@ -278,15 +370,38 @@ class Worker:
                 pending.append(cast("list[dict[str, object]]", item))
             now = time.monotonic()
             if len(pending) >= self.batch_size or now - last_flush >= self.flush_interval:
-                if pending:
-                    self._emit(pending)
-                    pending.clear()
+                self._emit_pending(pending)
                 # Advance the window even when idle (pending empty). Otherwise last_flush never
                 # moves while the queue is empty, timeout collapses to 0.0, and get(timeout=0.0)
                 # busy-spins a core. Resetting it lets the next get() block a full interval.
                 last_flush = now
         self._final_drain(pending)
 
+    def _emit_pending(self, pending: list[list[dict[str, object]]]) -> None:
+        """Emit ``pending`` if there is any, then clear it. The two always go together."""
+        if pending:
+            self._emit(pending)
+            pending.clear()
+
+    def _nothing_lost_since(self, marker: _FlushMarker) -> bool:
+        """Whether any batch was abandoned while ``marker`` was outstanding (SPEC-021 FR-001).
+
+        ``failed_batches`` moves exactly once per abandoned batch, so comparing it against the
+        marker's stamp answers "was anything lost while this flush was in flight" — which is the
+        question ``flush()`` asks, and a stronger one than "did *my* emit succeed". A marker whose
+        own emit found nothing pending still reports the loss if another flush's emit, or a
+        batching trigger's, abandoned a batch while it waited its turn.
+
+        Deliberately *not* a running "has anything ever failed" flag. That would make every empty
+        flush after a single bad batch report a failure it did not incur, contradicting the rule
+        that an empty drain is a successful one.
+
+        Called on the drain thread; the lock is for the counter's other readers, and is held only
+        for the read (``shutdown()`` releases it before ``join()``, so it cannot deadlock).
+        """
+        with self._lock:
+            return self.failed_batches == marker.seen_failures
+
     def _final_drain(self, pending: list[list[dict[str, object]]]) -> None:
         """On stop, pull anything still queued and emit the tail as one final batch."""
         markers: list[_FlushMarker] = []
@@ -298,15 +413,21 @@ class Worker:
             if isinstance(item, _FlushMarker):
                 # This guard is a second copy of _drain's and needs the same exclusion. Markers
                 # are answered *after* the final emit below, so a flush() that raced shutdown()
-                # still returns True — and truthfully: its events really did reach the sink.
+                # is answered by the drain that carried its events — with that drain's outcome.
                 markers.append(item)
                 continue
             if item is not None and item is not _SHUTDOWN:
                 pending.append(cast("list[dict[str, object]]", item))
-        if pending:
-            self._emit(pending)
-        for marker in markers:
-            marker.event.set()
+        try:
+            self._emit_pending(pending)
+            for marker in markers:
+                marker.delivered = self._nothing_lost_since(marker)
+        finally:
+            # In a ``finally`` so a ``BaseException`` from the final emit cannot strand a waiter
+            # for its whole timeout — the markers are released carrying their pessimistic
+            # default, which is the truth about a batch that died with this thread.
+            for marker in markers:
+                marker.event.set()
 
     def _emit(self, event_lists: list[list[dict[str, object]]]) -> None:
         """Flatten queued per-span event-lists into one batch and emit, retrying with backoff.
@@ -314,23 +435,33 @@ class Worker:
         A failing ``sink.emit`` is retried up to ``max_retries`` times; past that the batch is
         abandoned with a counted warning and draining continues, so a broken sink never crashes
         the worker thread or the app (FR-002, FR-003).
+
+        The outcome is not returned: ``failed_batches`` already moves exactly once per abandoned
+        batch, and that counter is what a waiting ``flush()`` is compared against (SPEC-021
+        FR-001), so a second channel for the same fact could only disagree with it.
+
+        ``max_retries`` is floored at zero so the loop always makes at least one attempt. A
+        negative value otherwise skipped the emit entirely and discarded the batch with no
+        attempt, no counter and nothing on stderr — a silent loss of exactly the kind this arc of
+        specs exists to remove, reachable only by misconfiguration but reachable.
         """
         batch = [event for events in event_lists for event in events]
         if not batch:
             return
-        for attempt in range(self.max_retries + 1):
+        retries = max(self.max_retries, 0)
+        for attempt in range(retries + 1):
             try:
                 self.sink.emit(batch)
                 return
             except Exception:  # any sink failure must not kill the worker thread
-                if attempt >= self.max_retries:
+                if attempt >= retries:
                     # Under the lock so a concurrent health() sees a coherent snapshot rather
                     # than a half-updated pair. No deadlock: shutdown() releases before join().
                     with self._lock:
                         self.failed_batches += 1
                     sys.stderr.write(
                         f"log-foundry: abandoned a batch of {len(batch)} event(s) after "
-                        f"{self.max_retries + 1} failed emit attempts\n"
+                        f"{retries + 1} failed emit attempts\n"
                     )
                     return
                 # Backoff between attempts; _stop.wait returns at once during shutdown, so a