log-foundry 0.10.2.dev68__tar.gz → 0.10.2.dev70__tar.gz

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev68
+Version: 0.10.2.dev70
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -233,6 +233,24 @@ is FIFO, everything submitted before the call is necessarily ahead of that marke
 exactly why the guarantee is "events submitted before this call", and why concurrent
 submissions from other threads may or may not be included.
 
+**`flush()` also empties the sink's own client buffer**, when the sink has one. A sink that
+buffers in a driver rather than writing through — `KafkaSink` hands to librdkafka, `PubSubSink`
+appends an unresolved future, `SentrySink` hands to the SDK's background transport — used to be
+unreachable this way, so `flush()` could return truthy with events sitting in a client. If that
+client cannot be emptied the result is falsy with `reason="sink-flush"`, which is distinct from
+`"abandoned"`: the events are past this library and inside a driver. A **custom sink** that
+buffers should implement `flush()` — it is optional, probed by name, and a sink without one is
+unaffected.
+
+**`flush()` also sweeps the spans that are still open**, so an in-span event does not have to wait
+for its span to close to be delivered. The span stays open and usable afterwards: its events go
+now and its `span.end` arrives later, in its own batch. Two consequences worth knowing. Boundary
+events swept this way carry the baggage as of the **flush** rather than as of the close, since
+that completion has to happen before they leave. And the sweep reaches only the **calling
+context's** spans — `contextvars` offers no way to enumerate another thread's or task's context,
+so a `flush()` in a handler that fanned out to tasks does not reach what those tasks have
+buffered; their events arrive when their own spans close.
+
 ## Usage
 
 ### `configure(...)`

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/README.md

@@ -197,6 +197,24 @@ is FIFO, everything submitted before the call is necessarily ahead of that marke
 exactly why the guarantee is "events submitted before this call", and why concurrent
 submissions from other threads may or may not be included.
 
+**`flush()` also empties the sink's own client buffer**, when the sink has one. A sink that
+buffers in a driver rather than writing through — `KafkaSink` hands to librdkafka, `PubSubSink`
+appends an unresolved future, `SentrySink` hands to the SDK's background transport — used to be
+unreachable this way, so `flush()` could return truthy with events sitting in a client. If that
+client cannot be emptied the result is falsy with `reason="sink-flush"`, which is distinct from
+`"abandoned"`: the events are past this library and inside a driver. A **custom sink** that
+buffers should implement `flush()` — it is optional, probed by name, and a sink without one is
+unaffected.
+
+**`flush()` also sweeps the spans that are still open**, so an in-span event does not have to wait
+for its span to close to be delivered. The span stays open and usable afterwards: its events go
+now and its `span.end` arrives later, in its own batch. Two consequences worth knowing. Boundary
+events swept this way carry the baggage as of the **flush** rather than as of the close, since
+that completion has to happen before they leave. And the sweep reaches only the **calling
+context's** spans — `contextvars` offers no way to enumerate another thread's or task's context,
+so a `flush()` in a handler that fanned out to tasks does not reach what those tasks have
+buffered; their events arrive when their own spans close.
+
 ## Usage
 
 ### `configure(...)`

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/pyproject.toml

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

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/__init__.py

@@ -44,7 +44,8 @@ def flush(timeout: float | None = 5.0) -> FlushResult:
       A :class:`FlushResult`. Truthy when the events submitted before this call reached the
       sink — so a truthy result means they were delivered, not merely that a drain took place.
       Falsy carries a ``reason`` naming which outcome occurred: ``"timed-out"``, ``"retired"``,
-      ``"thread-died"``, ``"queue-full"`` or ``"abandoned"``. It is falsy rather than ``False``:
+      ``"thread-died"``, ``"queue-full"``, ``"abandoned"`` or ``"sink-flush"`` — the last meaning
+      the queue drained but the sink could not empty its own client buffer (SPEC-036 FR-002). It is falsy rather than ``False``:
       ``if flush():`` is unchanged, but ``flush() is True`` can no longer hold, which is why the
       type had to change before ``1.0.0`` rather than after (SPEC-034 FR-007). Events submitted
       concurrently by another thread may or may not be included, since the caller cannot have

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/context.py

@@ -55,6 +55,27 @@ def current_span() -> Span | None:
     return stack[-1] if stack else None
 
 
+def _live_span_stack() -> tuple[Span, ...]:
+    """Returns every span open on this context, outermost first (SPEC-036 FR-001).
+
+    The library's non-copying read, named as :func:`_live_baggage` is and distinguished from the
+    public accessors for the same reason (SPEC-034 FR-003): a caller gets a copy, the library
+    reads the live object. There is nothing to copy here in any case — the stack is a tuple, so
+    handing it out cannot let anyone mutate it. :func:`current_span` returns only the innermost,
+    which is what an event needs and not what a sweep does.
+
+    Args:
+      None.
+
+    Returns:
+      Every span open on this context, outermost first. Empty when none is.
+
+    Raises:
+      None.
+    """
+    return _span_stack.get()
+
+
 def push_span(span: Span) -> contextvars.Token[tuple[Span, ...]]:
     """Pushes a span onto the stack.
 

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/decorator.py

@@ -22,6 +22,7 @@ from log_foundry.ids import (
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
 from log_foundry.results import ContinueResult, FlushResult
+from log_foundry.sinks.base import flush_sink
 from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_SWAP_TIMEOUT, Health, Worker
 
 if TYPE_CHECKING:
@@ -60,6 +61,13 @@ shutdown's event has every backoff collapsed to zero.
 """
 _orphan_retired = False
 
+_sweep_lock = threading.Lock()
+"""Serializes the span sweep, so two threads cannot deliver one span's buffer twice.
+
+The detach is a load and a store, and ``contextvars`` copies the same ``Span`` object into every
+task and into any ``copy_context()`` thread, so the two-reader case is ordinary rather than exotic
+(SPEC-036 FR-001 AC-10). A flush is not a hot path; a sink lock it is not competing with.
+"""
 _loss_lock = threading.Lock()
 """Guards the two loss counters, and deliberately not ``_worker_lock`` (SPEC-036 FR-003 AC-5).
 
@@ -197,6 +205,14 @@ def continue_trace(
         _diag.rejected("parent_span_id given with no trace_id to join", parent_span_id)
         announced = True
 
+    if adopted is not None and _current_span_was_swept():
+        _diag.rejected(
+            "the current span has already been flushed; trace context refused",
+            traceparent if traceparent is not None else str(trace_id),
+        )
+        adopted = None
+        announced = True
+
     if adopted is not None:
         context.set_adopted_context(*adopted)
         _reparent_current_span(*adopted)
@@ -214,6 +230,32 @@ def continue_trace(
     return ContinueResult(ok=False, reason="rejected" if announced else "nothing-supplied")
 
 
+def _current_span_was_swept() -> bool:
+    """Reports whether an in-span ``flush()`` has already shipped this span's events.
+
+    Read from ``context.current_span()`` — what :func:`_reparent_current_span` itself reads —
+    **and only when that span is a root**, which is the other half of that function's own guard.
+    A swept *child* is not a reason to refuse: the re-parent would have returned early on it and
+    rewritten nothing, so a refusal there prevents no corruption. It would still be wrong to
+    refuse — the two guards must agree, or the refusal fires where the thing it guards does not
+    run — though the adoption it spares reaches less than it appears to: SPEC-024 clears the
+    adopted context at the **root** span's close, so one made inside a child does not survive to
+    the next root span either. ``continue_trace``'s documented placement on the entry
+    point's first line is untouched either way: nothing has been swept that early.
+
+    Args:
+      None.
+
+    Returns:
+      Whether the current span is a root that has been swept.
+
+    Raises:
+      None.
+    """
+    span = context.current_span()
+    return span is not None and span.parent_span_id is None and span.swept
+
+
 def _reparent_current_span(trace_id: str, parent_span_id: str | None) -> None:
     """Moves an already-open root span into the adopted trace, events included.
 
@@ -712,33 +754,183 @@ def _adopt_declined_swap(new_sink: Sink) -> None:
         _orphan_sink = new_sink
 
 
+def _sweep_open_spans() -> None:
+    """Hands the worker every event buffered on an open span in this context (SPEC-036 FR-001).
+
+    An in-span event lives on ``span.events`` until the span *closes*, and ``Worker.flush``
+    drains the *queue* — so a ``flush()`` called inside a ``@trace``d function, which is where
+    the README's serverless recipe put it, had by construction nothing to drain. Measured: zero
+    of two events delivered, every counter clean, and ``FlushResult`` reporting ``reason=None``.
+
+    The span stays **open**: its events go now and its ``span.end`` arrives later in its own
+    batch. Closing and reopening was rejected — it would emit a ``span.end`` the function never
+    reached, with a fabricated ``duration_ms`` and ``status``.
+
+    Two things must happen before the events leave, and both are why this is not a one-liner.
+    The boundary events are backfilled **first**, because SPEC-015 completes them at close by
+    iterating ``span.events`` and a swept buffer would ship ``span.start`` with ``fields={}`` —
+    the very defect that spec exists to fix, recreated by any in-span flush. They therefore carry
+    the baggage as of the flush rather than as of the close, which is a real semantic change and
+    the alternative is mutating an event the worker already owns (SPEC-028). And the buffer is
+    **detached by swap**, never cleared: ``clear()`` empties the same list object the worker was
+    handed.
+
+    The worker is created when there is something to submit, and **resolved before the buffer is
+    detached**. That ordering is the whole of the difference between a lost batch and a delivered
+    one: ``_get_worker`` can raise — it ends in ``Thread.start()`` — and a detach that has already
+    happened leaves the events in a discarded local while the span reads empty and ``flush()``
+    reports success. Measured with the failure injected: 3 of 4 events destroyed, every counter
+    zero, on a span that was still open and would have delivered them at its close.
+    ``Worker.submit`` raises nothing, so once it is reached the batch is safe. Creating the worker
+    at all narrows SPEC-013's refusal rather than contradicting it — that exists so an *empty*
+    flush does not stand up a thread, and a sweep that found buffered events is not an empty
+    flush. A cold-start Lambda flushing before it returns is exactly this case: the worker is
+    built when the first span *closes*, so inside the first traced call there is none.
+
+    Concurrent sweeps are serialized on ``_sweep_lock``. The detach is a load and a store with a
+    real gap between them, and two threads sharing one ``Span`` — which ``contextvars`` makes
+    ordinary — can both read the same buffer and deliver it twice: measured, all 8 events
+    duplicated with the window held open, and 9 of 25 runs with only a GIL yield between them.
+    Rarely preempted on today's build is not a guarantee, and the floor is ``>=3.12`` where a
+    free-threading build removes even that. A flush is not a hot path, so a single lock is the
+    right cost.
+
+    **The detach stays one statement, and the two orderings above are not in tension.** A draft
+    hoisted the load to the top of the loop so a test could park on it — which put
+    ``_get_worker()``, and therefore ``Thread.start()``, *inside* the load-to-store gap: measured,
+    a sweep racing a close then delivered the whole batch twice, two ``span.end`` events among
+    them, in 67 of 100 unforced trials against 0 before.
+
+    One statement makes that gap **narrow, not closed**, and the difference matters. It compiles
+    to ``LOAD_ATTR … STORE_ATTR`` with no ``CALL`` between, so CPython's eval breaker never runs
+    there and today's GIL cannot switch inside it — 0 of 500 unforced trials. Forced with an
+    opcode-level preemption it reproduces 10 of 10, and a free-threaded build removes the
+    accident entirely while ``requires-python`` has no upper bound. So :func:`_flush` takes this
+    same lock rather than relying on the width of a window: that is the *detach-vs-detach* race,
+    and a process-global lock is the right instrument for it. The **append** race
+    (``api._log`` versus a detach) is a different window needing a per-span lock, and
+    ``architecture.md`` §13 declines it on cost.
+
+    It reaches only the calling context's spans. ``contextvars`` offers no way to enumerate
+    another thread's or task's context, so a ``flush()`` in a handler that fanned out does not
+    reach what those tasks buffered.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      Exception: Whatever building the worker raises. :func:`_flush_worker` guards it, because a
+        flush is the call most likely to be made in a ``finally``.
+    """
+    with _sweep_lock:
+        for span in context._live_span_stack():
+            if not span.events:
+                span.swept = True
+                continue
+            worker = _get_worker()
+            backfill_baggage(span, context._live_baggage())
+            span.swept = True
+            buffered, span.events = span.events, []
+            worker.submit(buffered)
+
+
+def _flush_live_sink() -> bool:
+    """Drains whatever the delivering sink holds in its own client (SPEC-036 FR-002).
+
+    Called **after** the queue drain, because the queue's events have to reach the client buffer
+    before it is emptied. A sink with no ``flush`` of its own is unaffected, which is what keeps
+    every pre-SPEC-036 sink satisfying the protocol.
+
+    Which sink is asked follows the ownership rule the rest of this module uses (SPEC-033): a
+    live worker's sink if there is one, otherwise the sink an orphan emit actually **reached**.
+    Not "a sink has been resolved" — ``configure()`` runs ``_ensure_sink()`` unconditionally, so a
+    bare ``configure(service=...)`` has already built a ``StdoutSink`` that nothing was ever
+    written to, and materialising a flush against it is the cost SPEC-031 FR-006 declined for the
+    close path for the same reason. So a ``flush()`` in a process that has never logged touches
+    no sink, which is what FR-001 AC-6 needs to stay true.
+
+    Args:
+      None.
+
+    Returns:
+      Whether the sink's own flush succeeded. ``True`` also when there was no sink to ask, or
+      when it holds nothing of its own.
+
+    Raises:
+      None. A failure is reported as a ``FlushResult`` reason by the caller, never raised: a
+        flush is the call most likely to be made in a ``finally``.
+    """
+    worker = _worker
+    sink = worker.sink if worker is not None and not worker.retired else _orphan_sink
+    if sink is None:
+        return True
+    try:
+        flush_sink(sink)
+    except Exception as exc:
+        _diag.absorbed("flushing the sink's own buffer", exc, "its client still holds events")
+        return False
+    return True
+
+
 def _flush_worker(timeout: float | None = 5.0) -> FlushResult:
     """Drains the process worker without retiring it, backing ``flush()`` (SPEC-013 FR-003).
 
-    This deliberately does not call :func:`_get_worker`: a process that never logged has
-    nothing to drain, and building a worker — with the thread and ``atexit`` registration
-    that brings — in order to flush nothing would be pure cost.
+    ~~This deliberately does not call :func:`_get_worker`~~ — narrowed by SPEC-036 FR-001. The
+    refusal still holds for an *empty* flush: a process that never logged has nothing to drain,
+    and building a worker — with the thread and ``atexit`` registration that brings — in order to
+    flush nothing would be pure cost. What changed is that :func:`_sweep_open_spans`, which runs
+    first, does build one when it finds buffered events on an open span, because submitting them
+    into a worker that does not exist delivers nothing and still reports success.
 
     Args:
       timeout: Seconds to wait for the drain, or ``None`` to wait indefinitely.
 
     Returns:
       A :class:`FlushResult`, truthy when everything outstanding was delivered and when no
-      worker exists — a process that never logged has nothing to drain, so it has lost
-      nothing.
+      worker exists — a process that never logged has nothing to drain, so it has lost nothing.
+      A sweep that could not hand its buffers over reports ``"abandoned"``, the existing token
+      for "this call did not deliver them" (SPEC-036 FR-001): the events are still on their open
+      spans and their close may yet carry them, but the caller asked *now*, and on the
+      cold-start path this exists for there may be no close — reporting success there is the
+      exact shape the spec was written to remove. The drain still runs, so whatever was
+      submitted before the failure is not held back by it.
+
+    The sink's own buffer is drained **whichever way the earlier steps went**, and the failure
+    reasons are decided afterwards. A draft returned early on a failed sweep or a dead drain
+    thread, which skipped it — and by then ``worker.flush`` had already pushed the queue *into*
+    that buffer, so the events most worth saving before a freeze were the ones left there. The
+    reason reported is the most upstream failure, because that is the one to fix.
 
     Raises:
       None. A flush is the call most likely to be made in a ``finally``, so the library must
         never be the reason a caller's function fails; a failure is reported by the return
         value instead (FR-003).
     """
-    worker = _worker
-    if worker is None:
-        return FlushResult(ok=True)
+    swept = True
     try:
-        return worker.flush(timeout)
-    except Exception:
+        _sweep_open_spans()
+    except Exception as exc:
+        _diag.absorbed("sweeping open spans for a flush", exc, "buffered events were not swept")
+        swept = False
+    worker = _worker
+    drained: FlushResult = FlushResult(ok=True)
+    thread_died = False
+    if worker is not None:
+        try:
+            drained = worker.flush(timeout)
+        except Exception:
+            thread_died = True
+    sink_drained = _flush_live_sink()
+    if not swept:
+        return FlushResult(ok=False, reason="abandoned")
+    if thread_died:
         return FlushResult(ok=False, reason="thread-died")
+    if not sink_drained:
+        return FlushResult(ok=False, reason="sink-flush")
+    return drained
 
 
 def _note_orphan_loss() -> None:
@@ -919,6 +1111,14 @@ def _flush(span: Span) -> None:
     The late append is now landing in a buffer nothing will emit, which is *also* loss — that
     half is ``api._log``'s, keyed on :attr:`Span.closed`.
 
+    It takes ``_sweep_lock`` for the detach, because :func:`_sweep_open_spans` performs the same
+    detach on the same attribute and a span can be swept and closed concurrently — measured, the
+    whole batch delivered twice with two ``span.end`` events among them. The hold covers one
+    statement and not the submit; ``Worker.submit`` is a ``put_nowait`` that never blocks, and the
+    cost of the lock on the traced path measured within noise (+0.4% single-threaded, +0.9% across
+    eight threads, 20,000 spans each). The **append** window this does not close is a different
+    one, needs a per-span lock, and is declined in ``architecture.md`` §13.
+
     Args:
       span: The finished span whose buffered events are submitted.
 
@@ -928,7 +1128,8 @@ def _flush(span: Span) -> None:
     Raises:
       Exception: Whatever creating the worker or submitting raises; :func:`_end` is the guard.
     """
-    events, span.events = span.events, []
+    with _sweep_lock:
+        events, span.events = span.events, []
     _get_worker().submit(events)
 
 

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/model.py

@@ -36,6 +36,18 @@ class Span:
     span, so a fire-and-forget ``create_task`` can outlive its parent and append to a buffer
     nothing will emit again. It is read by ``api._log`` at append time, which is the only place
     that can notice: nothing in the library looks at a span after ``_close_span`` returns.
+
+    ``swept`` marks a span whose buffered events an in-span ``flush()`` has already handed to the
+    worker (SPEC-036 FR-001). Nothing in the delivery path needs it — the sweep is correct without
+    it — but ``continue_trace`` does: ``_reparent_current_span`` adopts a context by rewriting the
+    events still *buffered* on the open root span, and swept events have left that buffer, so an
+    adoption after a sweep would leave one span carrying two trace ids. That is the SPEC-024
+    category, wrong data rather than lost data, so the flag lets the adoption refuse instead.
+
+    The guarantee is **single-threaded**. The flag is not a synchronization primitive:
+    ``continue_trace`` reads it and then re-parents across an ordinary function call, so a sweep
+    arriving in that gap still splits the span. It is set before the detach so a concurrent reader
+    errs toward refusing, and the residual is recorded in ``architecture.md`` §13.
     """
 
     trace_id: str
@@ -46,6 +58,7 @@ class Span:
     defaults: dict[str, object] = field(default_factory=dict)
     events: list[dict[str, object]] = field(default_factory=list)
     closed: bool = False
+    swept: bool = False
 
 
 def _iso_now() -> str:

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/results.py

@@ -50,7 +50,13 @@ class FlushResult(_Result):
     """What :func:`log_foundry.flush` returns.
 
     ``reason`` is ``None`` on success. The tokens it can carry today are ``"timed-out"``,
-    ``"retired"``, ``"thread-died"``, ``"queue-full"`` and ``"abandoned"``.
+    ``"retired"``, ``"thread-died"``, ``"queue-full"``, ``"abandoned"`` and ``"sink-flush"``.
+
+    ``"sink-flush"`` is the one SPEC-036 added (FR-002 AC-8) and it is worth distinguishing: the
+    queue drained cleanly and the **sink's own client buffer** did not, so the events are past
+    this library and inside a driver. ``"abandoned"`` is the neighbouring case where this call
+    could not hand them over at all. New tokens may appear in any release, which is what this
+    type exists for — branch on ``bool()``.
     """
 
 

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/_socket.py

@@ -118,6 +118,10 @@ class SocketTransport:
       failed: Messages abandoned past the reconnect-retry bound.
       dropped_oversized: UDP datagrams discarded before any send for exceeding
         ``max_datagram_bytes``.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``send_all`` puts the bytes on the
+    socket before it returns, and no client object outlives it holding data.
     """
 
     def __init__(

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/base.py

@@ -6,7 +6,7 @@ from abc import abstractmethod
 from dataclasses import dataclass
 from typing import Protocol, runtime_checkable
 
-__all__ = ["Sink", "SinkDeliveryError", "SinkLosses", "read_losses"]
+__all__ = ["Sink", "SinkDeliveryError", "SinkLosses", "flush_sink", "read_losses"]
 
 
 class SinkDeliveryError(Exception):
@@ -142,6 +142,24 @@ class Sink(Protocol):
     the call an operator makes when a destination is already hanging, and sharing one lock
     would make that poll wait for an in-flight emit and its retry backoff. Where a sink holds
     both, the order is always transport then counter, never the reverse.
+    A sixth is optional in the same way: ``flush() -> None``, which drains whatever the sink is
+    holding in its **client** without closing it (SPEC-036 FR-002). A sink that buffers in a
+    driver rather than writing through — ``KafkaSink`` hands to librdkafka, ``GooglePubSubSink``
+    appends an unresolved future — is unreachable through ``log_foundry.flush()`` without it:
+    measured against a stand-in with that shape, ``flush() -> True``, on the wire 0, in the
+    client buffer 3, ``health()`` all zeros. It is called **after** the queue drain, so the
+    queue's events have reached the client buffer before it is emptied.
+
+    It is **not a close**, and the difference is the whole point: the sink keeps its transport and
+    goes on accepting events afterwards. Like :meth:`emit` it must tolerate being called
+    concurrently with an emit (SPEC-028), and like :meth:`emit` it must **raise** when it could
+    not deliver what it was holding — that is the only channel by which ``log_foundry.flush()``
+    can report ``reason="sink-flush"`` instead of success. :func:`flush_sink` is the probe, and it
+    deliberately does **not** behave like :func:`read_losses`: that one swallows a raising
+    accessor because a broken reporter must not take ``health()`` down, while this one propagates,
+    because a swallowed flush failure is exactly the "sink the worker believes" this file exists
+    to prevent.
+
     """
 
     @abstractmethod
@@ -260,3 +278,32 @@ def read_losses(sink: object) -> SinkLosses | None:
     except Exception:
         return None
     return losses if isinstance(losses, SinkLosses) else None
+
+
+def flush_sink(sink: object) -> bool:
+    """Calls a sink's optional ``flush()``, letting any failure propagate (SPEC-036 FR-002).
+
+    The sibling of :func:`read_losses`, written here for the same reason — the probe and its
+    guarantees belong in one place — and with the **opposite** failure rule, which is the part
+    worth reading twice. ``read_losses`` swallows a raising accessor because a broken reporter
+    must not take ``health()`` down with it. This one must not swallow anything: a sink's flush
+    failure reaches the caller only through ``log_foundry.flush()``'s result, so absorbing it here
+    would produce the exact "sink the worker believes" this module exists to prevent — a
+    ``flush()`` reporting success over a client buffer that never went out.
+
+    Args:
+      sink: The sink to probe, of any type.
+
+    Returns:
+      Whether the sink had a ``flush`` to call. ``False`` means it holds nothing of its own, and
+      the queue drain was the whole of the flush.
+
+    Raises:
+      Exception: Whatever the sink's ``flush`` raises, deliberately unguarded. The caller turns
+        it into a ``FlushResult`` reason; see ``decorator._flush_live_sink``.
+    """
+    accessor = getattr(sink, "flush", None)
+    if not callable(accessor):
+        return False
+    accessor()
+    return True

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/callback.py

@@ -22,6 +22,11 @@ class CallbackSink:
     (SPEC-032 FR-003). Both decisions belong to the callable: this class holds nothing, and what
     a hook releases is not knowable from here — a callable needing either guarantee must provide
     it, exactly as a hand-written ``Sink`` implementation would.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): it hands each event to a *function*, which
+    has returned by the time ``emit`` does. Unlike the three wrapper sinks it wraps no sink, so
+    there is nothing to forward a flush to.
     """
 
     def __init__(

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/clickhouse.py

@@ -47,6 +47,10 @@ class ClickHouseSink:
     default auto-generated session, so it is squarely in that case and the lock is required
     rather than merely prudent. One client per thread would be the alternative, and that is the
     connection-pool design FR-002 puts out of scope.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): the driver call returns only once the
+    destination has the batch, so nothing is queued locally between emits.
     """
 
     def __init__(

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/datadog.py

@@ -28,6 +28,10 @@ class DatadogSink(HTTPSink):
         sink in the family whose per-event limit is stricter than its request limit, so without
         it a 2 MB event passes the 5 MB request budget and is rejected by a limit the budget
         cannot see. All three are the vendor's own figures, from the Logs API's send-logs limits.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): each ``emit`` is a request that has
+    completed by the time it returns, and no client object outlives it holding data.
     """
 
     MAX_BATCH_COUNT = 1000

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/elasticsearch.py

@@ -38,6 +38,10 @@ class ElasticsearchSink(HTTPSink):
         bulk guidance is to find a working size by experiment rather than to send the largest
         request the server will accept, and a 100 MB bulk is a poor default for a log shipper.
         Raise it with ``max_batch_bytes=``.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): each ``emit`` is a request that has
+    completed by the time it returns, and no client object outlives it holding data.
     """
 
     MAX_BATCH_COUNT = 1000
@@ -201,4 +205,8 @@ class OpenSearchSink(ElasticsearchSink):
     """OpenSearch reuses the Elasticsearch ``_bulk`` protocol verbatim (FR-003).
 
     Endpoint and auth differ only by configuration, so this is a straight reuse.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): each ``emit`` is a request that has
+    completed by the time it returns, and no client object outlives it holding data.
     """

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/eventhubs.py

@@ -23,6 +23,10 @@ class AzureEventHubsSink:
     1 MB per-batch limit, which the SDK signals by raising ``ValueError`` from ``add``. The
     worst-case delay (SPEC-027 FR-005) is ``max_retries`` interruptible waits per batch, 0.7 s at
     the defaults.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): the driver call returns only once the
+    destination has the batch, so nothing is queued locally between emits.
     """
 
     def __init__(

{log_foundry-0.10.2.dev68 → log_foundry-0.10.2.dev70}/src/log_foundry/sinks/file.py

@@ -71,6 +71,10 @@ class FileSink:
     concurrently (SPEC-028 FR-002) — this module claimed a single worker thread until that spec
     measured the orphan path emitting on application threads at the same time. Cross-*process*
     coordination remains out of scope: two processes appending to one path are on their own.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``emit`` flushes the stream before it
+    returns, so nothing of this sink's is left pending between calls.
     """
 
     def __init__(self, path: str, *, encoding: str = "utf-8") -> None:
@@ -211,6 +215,10 @@ class RotatingFileSink:
     damage: a second thread mid-``emit`` could write to the handle rotation had just closed, or
     to the pre-rotation file it had already renamed away. Both are serialized on a lock
     (SPEC-028 FR-002).
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``emit`` flushes the stream before it
+    returns, so nothing of this sink's is left pending between calls.
     """
 
     def __init__(