log-foundry 0.10.2.dev69__tar.gz → 0.10.2.dev71__tar.gz

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev69
+Version: 0.10.2.dev71
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -233,6 +233,15 @@ 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

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/README.md

@@ -197,6 +197,15 @@ 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

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/pyproject.toml

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

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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:
@@ -836,6 +837,44 @@ def _sweep_open_spans() -> None:
             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).
 
@@ -859,6 +898,12 @@ def _flush_worker(timeout: float | None = 5.0) -> FlushResult:
       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
@@ -871,15 +916,21 @@ def _flush_worker(timeout: float | None = 5.0) -> FlushResult:
         _diag.absorbed("sweeping open spans for a flush", exc, "buffered events were not swept")
         swept = False
     worker = _worker
-    if worker is None:
-        return FlushResult(ok=True) if swept else FlushResult(ok=False, reason="abandoned")
-    try:
-        if swept:
-            return worker.flush(timeout)
-        worker.flush(timeout)
-    except Exception:
+    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")
-    return FlushResult(ok=False, reason="abandoned")
+    if not sink_drained:
+        return FlushResult(ok=False, reason="sink-flush")
+    return drained
 
 
 def _note_orphan_loss() -> None:

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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.dev69 → log_foundry-0.10.2.dev71}/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__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/filtering.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from log_foundry import _diag, _lifecycle
-from log_foundry.sinks.base import read_losses
+from log_foundry.sinks.base import flush_sink, read_losses
 
 if TYPE_CHECKING:
     import threading
@@ -28,6 +28,13 @@ class FilteringSink:
     It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
     (SPEC-032 FR-003): it holds no transport and its ``close()`` only forwards, so both decisions
     belong to the inner sink. A guard here would refuse batches the inner sink would have taken.
+
+
+    It holds **no** client buffer of its own, but it **forwards** ``flush()`` to what it wraps
+    (SPEC-036 FR-002). Holding nothing is not the same as having nothing to do: a wrapper that
+    did not forward would leave a buffering child unreachable through ``log_foundry.flush()``
+    while looking fine — the SPEC-027 lesson about ``log_foundry_stop_signal``, that a signal
+    stopped at a wrapper reaches nothing and moves the defect rather than fixing it.
     """
 
     def __init__(
@@ -147,6 +154,25 @@ class FilteringSink:
                 f"{type(self._inner).__name__} stays uninterruptible",
             )
 
+    def flush(self) -> None:
+        """Forwards the flush to the wrapped sink (SPEC-036 FR-002).
+
+        This wrapper holds nothing itself, but a wrapper that did not forward would leave a
+        buffering inner sink unreachable through ``log_foundry.flush()`` while looking fine —
+        the SPEC-027 lesson that a signal stopped at a wrapper reaches nothing.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: Whatever the wrapped sink raises, so the failure reaches the caller as a
+            ``FlushResult`` reason rather than being swallowed here.
+        """
+        flush_sink(self._inner)
+
     def losses(self) -> SinkLosses | None:
         """Reports the inner sink's losses (SPEC-026 FR-002).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/firehose.py

@@ -40,6 +40,10 @@ class FirehoseSink:
     It also **adds no post-close guard** (SPEC-032 FR-003): ``close()`` is a documented no-op,
     because the client is the caller's to release or the SDK's to reap, so a batch emitted
     afterwards still reaches the delivery stream.
+
+
+    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.
     """
 
     MAX_RECORDS = 500

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/honeycomb.py

@@ -24,6 +24,10 @@ class HoneycombSink(HTTPSink):
         maximum event count for the batch endpoint.
       MAX_BATCH_BYTES: 1,000,000 — Honeycomb's documented 1 MB of uncompressed JSON for the
         Create Events endpoint.
+
+
+    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.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/http.py

@@ -201,6 +201,10 @@ class HTTPSink:
     And it **adds no post-close guard** (SPEC-032 FR-003), because ``close()`` releases nothing —
     a batch emitted afterwards still reaches the endpoint, and refusing it would be loss the
     library invented rather than loss it reported.
+
+
+    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 = DEFAULT_MAX_BATCH_COUNT

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/kafka.py

@@ -228,6 +228,41 @@ class KafkaSink:
             self._closed = True
             self._flush_bounded()
 
+    def flush(self) -> None:
+        """Drains the producer's local buffer without closing the sink (SPEC-036 FR-002).
+
+        ``emit`` hands to librdkafka and returns; only ``flush()`` drains it. Before this hook
+        existed the buffer was unreachable through ``log_foundry.flush()`` — the whole point of
+        that call in a process about to be frozen — and went out only at ``close()``.
+
+        It **raises** when the producer still holds messages after ``flush_timeout``, which is what
+        makes ``log_foundry.flush()`` report ``reason="sink-flush"`` rather than success. Nothing
+        is counted as lost: unlike the close path those messages are still queued and the next
+        flush or the close may yet deliver them, so booking them against ``failed`` would report a
+        loss that has not happened. The remainder is named in the error instead.
+
+        Refuses after ``close()`` on SPEC-032's rule — the producer has been flushed and released.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          SinkDeliveryError: The sink is closed, or the producer could not be drained inside
+            ``flush_timeout``.
+          Exception: Whatever the producer raises.
+        """
+        if self._closed:
+            raise SinkDeliveryError("KafkaSink cannot flush: the sink is closed")
+        remaining = self.producer.flush(self.flush_timeout)
+        if type(remaining) is int and remaining > 0:
+            raise SinkDeliveryError(
+                f"KafkaSink flushed within {self.flush_timeout}s with {remaining} "
+                "message(s) still queued"
+            )
+
     def _flush_bounded(self) -> None:
         """Flushes the producer within a bound, counting whatever it could not deliver (FR-006).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/kinesis.py

@@ -40,6 +40,10 @@ class KinesisSink:
     It also **adds no post-close guard** (SPEC-032 FR-003): ``close()`` is a documented no-op,
     because the client is the caller's to release or the SDK's to reap, so a batch emitted
     afterwards still reaches the stream.
+
+
+    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.
     """
 
     MAX_RECORDS = 500

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/logging_sink.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import logging
 
+from log_foundry import _diag
+
 __all__ = ["LoggingSink"]
 
 _LEVELS = {
@@ -41,6 +43,14 @@ class LoggingSink:
     and this sink holds nothing else. And it **adds no post-close guard** (SPEC-032 FR-003) —
     ``close()`` is a no-op by design, since tearing down handlers this sink did not configure is
     not its to do, so a later batch still reaches the framework.
+
+
+    Its transport is the **handler chain**, and it forwards ``flush()`` onto it (SPEC-036
+    FR-002). A first pass filed this alongside ``MemorySink`` and ``NullSink`` as having nothing
+    underneath, which is wrong: ``logging.Handler.flush`` exists precisely because handlers
+    buffer, ``logging.handlers.MemoryHandler`` does nothing else, and ``QueueHandler`` and most
+    third-party handlers are the same shape. Measured against a ``MemoryHandler``: three events
+    emitted, nothing on the stream, and everything on it after one ``flush()``.
     """
 
     def __init__(
@@ -79,6 +89,47 @@ class LoggingSink:
         for event in batch:
             self._logger.handle(self._to_record(event))
 
+    def flush(self) -> None:
+        """Flushes the logger's handlers, and its ancestors' unless propagation is off.
+
+        The handler chain is this sink's transport, so this walks it the way ``logging`` itself
+        dispatches a record — the current logger's handlers, then each ancestor's, stopping where
+        ``propagate`` is ``False``. Anything else would flush a handler the events never reached,
+        or miss the one they did.
+
+        Every handler is attempted before anything is raised, and then the first failure is —
+        ``MultiSink.flush``'s rule, for its reason: one broken handler must not leave a healthy
+        one downstream of it unflushed. Failures are **not** absorbed, because a handler that
+        could not flush is a client buffer that did not go out, which ``log_foundry.flush()``
+        reports as ``reason="sink-flush"``.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: The first handler's exception, when any handler could not be flushed.
+        """
+        first_error: Exception | None = None
+        logger: logging.Logger | None = self._logger
+        while logger is not None:
+            for handler in logger.handlers:
+                try:
+                    handler.flush()
+                except Exception as err:
+                    if first_error is None:
+                        first_error = err
+                    _diag.absorbed(
+                        "flushing a logging handler",
+                        err,
+                        f"{type(handler).__name__} still holds records",
+                    )
+            logger = logger.parent if logger.propagate else None
+        if first_error is not None:
+            raise first_error
+
     def close(self) -> None:
         """Does nothing, since the sink does not own the user's logging configuration (FR-005).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/logstash.py

@@ -44,6 +44,11 @@ class LogstashSink:
     ``SinkDeliveryError`` and reopens nothing, while in HTTP mode ``close()`` released nothing
     and the batch still ships. Both are the backend's answer, correctly, rather than one this
     class invents on top.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): each ``emit`` hands its bytes to the
+    socket before it returns, and no client object outlives it holding data. What the *network*
+    then does with a datagram is not something a flush could hurry.
     """
 
     def __init__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/loki.py

@@ -38,6 +38,10 @@ class LokiSink(HTTPSink):
         (``distributor.max_recv_msg_size``, 100 MB for the compressed body), but that is an
         operator-tunable server setting and a hosted Loki is routinely configured well below it,
         so the default here is the conservative one. 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

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/memory.py

@@ -16,6 +16,10 @@ class MemorySink:
     It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
     (SPEC-032 FR-003): there is no transport, and ``close()`` releases nothing — a test that
     closes the sink and then asserts on a later batch still sees it in ``.events``.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): there is no transport under it for a flush
+    to push anything onto.
     """
 
     def __init__(self, maxlen: int | None = None) -> None:

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/mongodb.py

@@ -35,6 +35,10 @@ class MongoDBSink:
     Attributes:
       failed: Documents the server rejected, or a whole batch abandoned past the retry bound.
       dropped_oversized: Documents dropped for exceeding MongoDB's 16 MB per-document limit.
+
+
+    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.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/multi.py

@@ -6,7 +6,7 @@ import threading
 from typing import TYPE_CHECKING
 
 from log_foundry import _diag, _lifecycle
-from log_foundry.sinks.base import SinkLosses, read_losses
+from log_foundry.sinks.base import SinkLosses, flush_sink, read_losses
 
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
@@ -36,6 +36,13 @@ class MultiSink:
     ``close()`` here only forwards, so a guard added at this level would refuse batches the
     children would have taken, while a child that must refuse already does and is counted here
     like any other failure.
+
+
+    It holds **no** client buffer of its own, but it **forwards** ``flush()`` to what it wraps
+    (SPEC-036 FR-002). Holding nothing is not the same as having nothing to do: a wrapper that
+    did not forward would leave a buffering child unreachable through ``log_foundry.flush()``
+    while looking fine — the SPEC-027 lesson about ``log_foundry_stop_signal``, that a signal
+    stopped at a wrapper reaches nothing and moves the defect rather than fixing it.
     """
 
     def __init__(self, *sinks: Sink) -> None:
@@ -155,6 +162,44 @@ class MultiSink:
                     f"{type(sink).__name__} stays uninterruptible",
                 )
 
+    def flush(self) -> None:
+        """Forwards the flush to every child, so a buffering one is actually reached.
+
+        SPEC-036 FR-002. Without this a ``MultiSink(StdoutSink(), KafkaSink(...))`` — the
+        composition the README itself shows — left every Kafka message in librdkafka's buffer
+        while ``log_foundry.flush()`` reported success: measured, 0 on the wire and 3 in the
+        client. That is the SPEC-027 shape exactly, where a stop signal set on a wrapper reached
+        nothing.
+
+        Every child is attempted before anything is raised, so one failing child cannot stop a
+        healthy sibling being drained — the isolation :meth:`emit` applies, for the same reason.
+        The raise rule is **different** from ``emit``'s, and deliberately: ``emit`` raises only on
+        total failure because the worker retries a raised batch and a partial retry duplicates.
+        Nothing retries a flush, and the caller asked whether everything is out, so **any** child
+        that could not be drained makes the answer no.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: The first child's exception, when any child could not be flushed.
+        """
+        first_error: Exception | None = None
+        for sink in self._sinks:
+            try:
+                flush_sink(sink)
+            except Exception as err:
+                if first_error is None:
+                    first_error = err
+                _diag.absorbed(
+                    "flushing a MultiSink child", err, f"{type(sink).__name__} still holds events"
+                )
+        if first_error is not None:
+            raise first_error
+
     def losses(self) -> SinkLosses | None:
         """Sums the children's losses so a fan-out reports the whole tree (SPEC-026 FR-002).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/nats.py

@@ -152,6 +152,53 @@ class NATSSink:
         if batch and not published:
             raise SinkDeliveryError(f"NATSSink published none of {len(batch)} event(s)")
 
+    def flush(self) -> None:
+        """Pushes the client's outbound buffer onto the wire without closing (SPEC-036 FR-002).
+
+        Core ``publish()`` writes into the client's own outbound buffer and returns; the network
+        write happens on the driver's flusher task. That is why :meth:`close` drains, and why
+        ``log_foundry.flush()`` could not reach a published-but-unwritten event before this hook.
+        Under JetStream ``publish()`` awaits an ack, so there is nothing pending and this costs a
+        round trip at worst.
+
+        Takes the same lock :meth:`emit` does, for the reason recorded there: an ``asyncio`` loop
+        is single-entry, and a second thread calling ``run_until_complete`` on a running loop can
+        leave a thread never returning at all.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          SinkDeliveryError: The sink is closed.
+          Exception: Whatever the driver raises while flushing.
+        """
+        with self._lock:
+            if self._loop.is_closed():
+                raise SinkDeliveryError("NATSSink cannot flush: the sink is closed")
+            self._loop.run_until_complete(self._flush_client())
+
+    async def _flush_client(self) -> None:
+        """Flushes the client if the driver offers one, mirroring :meth:`_drain`'s probe.
+
+        Probed by name for the same reason ``drain`` is: the sink is written against a driver it
+        does not own, and a client without the method has nothing buffered to push.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: Whatever the driver raises while flushing.
+        """
+        flush = getattr(self._client, "flush", None)
+        if flush is not None:
+            await flush()
+
     async def _drain(self) -> None:
         """Drains the client if the driver offers a drain.
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/newrelic.py

@@ -20,6 +20,10 @@ class NewRelicSink(HTTPSink):
         maximum entry count, only a payload size.
       MAX_BATCH_BYTES: 1,000,000 — the Log API's documented "1MB (10^6 bytes) maximum per POST".
         Measured uncompressed here, which is the conservative reading when ``gzip=True``.
+
+
+    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.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/null.py

@@ -19,6 +19,10 @@ class NullSink:
     It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
     (SPEC-032 FR-003): there is no transport and ``close()`` releases nothing, so discarding a
     batch after close is the same operation as discarding one before it.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): there is no transport under it for a flush
+    to push anything onto.
     """
 
     def __init__(self) -> None:

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/postgres.py

@@ -32,6 +32,11 @@ class PostgresSink:
     ``commit`` publishes the other's half-written batch, and its ``rollback`` on a failure
     discards rows the other had already inserted and is about to report as delivered. A lock
     gives the sequence the exclusivity it was written for.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``emit`` commits its own transaction, so
+    nothing is uncommitted once it returns. The commit in ``close`` is belt and braces, not a
+    buffer.
     """
 
     def __init__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/pubsub.py

@@ -403,6 +403,79 @@ class GooglePubSubSink:
             _diag.lost("event", 1, f"GooglePubSubSink publish unconfirmed, {type(err).__name__}")
         return True
 
+    def flush(self) -> None:
+        """Resolves the outstanding publish futures without closing the sink (SPEC-036 FR-002).
+
+        ``emit`` appends an unresolved future and returns; before this hook existed nothing but
+        ``close()`` ever called ``result()`` on them, so ``log_foundry.flush()`` could not reach a
+        single one — the call whose whole purpose is delivery before a freeze.
+
+        **It is :meth:`_await_overflow` applied to the whole pending list, and the three rules it
+        obeys are that method's, each earned by a measured defect.** One ``deadline`` covers the
+        list rather than a timeout per future: at the shipped ``max_pending`` a per-future wait is
+        not a bound at all, and a stalled destination would hold ``log_foundry.flush()`` for
+        hours. ``_Unboundable`` is **caught**, because a future whose ``result()`` takes no
+        ``timeout`` cannot be waited on within one — and letting it escape here would abandon the
+        entire list, which has already been swapped out and is referenced by nothing else. And
+        ``_futures_lock`` is **not** held across a ``result()``, because ``emit`` takes it per
+        event and an application thread on the orphan path would block behind it.
+
+        A future that did not settle is put back rather than dropped: the sink stays open, so it
+        is unfinished, not unconfirmed, and the next flush or the close waits on it again. It
+        **raises** when any remained, which is what makes ``log_foundry.flush()`` report
+        ``reason="sink-flush"``. A future that settled *failed* is already counted by
+        :meth:`_resolve` and reported through ``losses()``, per SPEC-026.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          SinkDeliveryError: The sink is closed, or a publish was still in flight afterwards.
+        """
+        if self._closed:
+            raise SinkDeliveryError("GooglePubSubSink cannot flush: the sink is closed")
+        with self._futures_lock:
+            pending, self._futures = self._futures, []
+        if not pending:
+            return
+
+        deadline = time.monotonic() + self.overflow_timeout
+        unresolved: list[Any] = []
+        for index, future in enumerate(pending):
+            settled = False
+            while not self._out_of_time(deadline):
+                began = time.monotonic()
+                slice_ = min(deadline - began, _POLL_INTERVAL)
+                try:
+                    settled = self._resolve(future, slice_)
+                except _Unboundable:
+                    break
+                if settled:
+                    break
+                wait(slice_ - (time.monotonic() - began), self.log_foundry_stop_signal)
+            if settled:
+                continue
+            unresolved.append(future)
+            if self._out_of_time(deadline):
+                unresolved.extend(pending[index + 1 :])
+                break
+
+        if not unresolved:
+            return
+        with self._futures_lock:
+            closed = self._closed
+            if not closed:
+                self._futures[:0] = unresolved
+        if closed:
+            for future in unresolved:
+                self._resolve(future)
+        raise SinkDeliveryError(
+            f"GooglePubSubSink flushed with {len(unresolved)} publish(es) still in flight"
+        )
+
     def close(self) -> None:
         """Resolves all pending publish futures, counting and logging errors (FR-008).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/rabbitmq.py

@@ -33,6 +33,12 @@ class RabbitMQSink:
     event is published as a persistent message to the configured exchange and routing key, and a
     dropped or closed connection is re-established within a bounded retry. The worst-case delay
     (SPEC-027 FR-005) is ``max_retries`` interruptible waits per message, 0.7 s at the defaults.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``basic_publish`` writes the frame
+    before it returns, so nothing is queued locally between emits. This sink does not enable
+    publisher confirms, so "written" is not "acknowledged" — but that is a delivery-guarantee
+    question, not a buffer a flush could empty.
     """
 
     def __init__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/redis.py

@@ -34,6 +34,10 @@ class _RedisSink:
     command, so a batch emitted after ``shutdown()`` opened a connection nothing would ever
     reap — the same leak SPEC-028's review found in ``RabbitMQSink``, whose ``_active_channel``
     reopened whatever ``close()`` had released.
+
+
+    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__(self, *, client: Any, url: str | None, max_retries: int) -> None:
@@ -172,7 +176,11 @@ class _RedisSink:
 
 
 class RedisStreamsSink(_RedisSink):
-    """Appends each event to a Redis stream via ``XADD``, pipelined per batch (FR-005)."""
+    """Appends each event to a Redis stream via ``XADD``, pipelined per batch (FR-005).
+
+    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__(
         self,
@@ -235,7 +243,11 @@ class RedisStreamsSink(_RedisSink):
 
 
 class RedisListSink(_RedisSink):
-    """Pushes each event onto a Redis list via ``RPUSH``, pipelined per batch (FR-005)."""
+    """Pushes each event onto a Redis list via ``RPUSH``, pipelined per batch (FR-005).
+
+    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__(
         self,

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/sentry.py

@@ -122,6 +122,45 @@ class SentrySink:
                 f"SentrySink delivered none of {attempted} qualifying event(s)"
             )
 
+    def flush(self) -> None:
+        """Pushes the Sentry SDK's own transport queue, which nothing else here ever does.
+
+        SPEC-036 FR-002, and a case SPEC-042's measured roster of five did not reach: that roster
+        was derived from what a *refused close* costs, and :meth:`close` releases nothing here, so
+        this sink never appeared in it. ``capture_event`` hands to the SDK's **background
+        transport** and returns, so without this hook an event accepted by Sentry's client was
+        unreachable through ``log_foundry.flush()`` and went out only when the SDK's own timer or
+        interpreter exit got to it.
+
+        Only the injected-or-imported SDK client has a queue. The ``urllib`` fallback posts an
+        envelope per event and holds nothing, so with no client this is correctly a no-op.
+
+        ``Client.flush`` is probed by name, as every optional member the library calls on an object
+        it does not own is: a stand-in ``client=`` satisfying only ``capture_event`` stays valid,
+        which is what the injected-client tests use.
+
+        **It cannot report a failure, and that is the SDK's shape rather than a choice here.**
+        ``sentry_sdk.Client.flush`` logs a warning and returns ``None`` when its own timeout
+        expires, so a queue the SDK just gave up on is indistinguishable from one it drained, and
+        ``log_foundry.flush()`` reports success either way. Recorded rather than worked around: the
+        alternatives are reading a private attribute or timing the call, and both would invent a
+        verdict the SDK declines to give.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: Whatever the SDK raises while flushing.
+        """
+        if self.client is None:
+            return
+        flush = getattr(self.client, "flush", None)
+        if callable(flush):
+            flush()
+
     def close(self) -> None:
         """Forwards to the HTTP fallback, whose own close releases nothing (FR-012).
 

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/sns.py

@@ -33,6 +33,10 @@ class SNSSink:
     It also **adds no post-close guard** (SPEC-032 FR-003): ``close()`` is a documented no-op,
     because the client is the caller's to release or the SDK's to reap, so a batch emitted
     afterwards still reaches the topic.
+
+
+    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.
     """
 
     MAX_BATCH = 10

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/splunk.py

@@ -28,6 +28,10 @@ class SplunkHECSink(HTTPSink):
         it is ``max_content_length`` on the receiving instance, so there is no vendor figure to
         cite and the default is chosen rather than documented. Raise it with
         ``max_batch_bytes=`` to match your deployment.
+
+
+    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.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/sqlite.py

@@ -28,6 +28,11 @@ class SQLiteSink:
     implicit transaction, so one thread's rollback discards rows the other had already inserted.
     A lock restores the one-writer-at-a-time the guard used to enforce. Cross-*process* writers
     to one database file remain out of scope.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): ``emit`` commits its own transaction, so
+    nothing is uncommitted once it returns. The commit in ``close`` is belt and braces, not a
+    buffer.
     """
 
     def __init__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/sqs.py

@@ -95,6 +95,10 @@ class SQSSink:
     It also **adds no post-close guard** (SPEC-032 FR-003): ``close()`` is a documented no-op,
     because the client is the caller's to release or the SDK's to reap, so a batch emitted
     afterwards still reaches the queue.
+
+
+    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.
     """
 
     MAX_BATCH = 10

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/stdout.py

@@ -26,6 +26,10 @@ class StdoutSink:
 
     It **adds no post-close guard** (SPEC-032 FR-003), because ``close()`` only flushes — the
     stream belongs to the process, not to this sink, so a later batch still lands.
+
+
+    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, stream: TextIO | None = None) -> None:
@@ -84,6 +88,10 @@ class StderrSink(StdoutSink):
     It writes each event as one ``json.dumps`` line and flushes, exactly like ``StdoutSink`` —
     only the default stream differs, following the twelve-factor convention of logs on stderr
     and app output on stdout.
+
+
+    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, stream: TextIO | None = None) -> None:

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/syslog.py

@@ -51,6 +51,11 @@ class SyslogSink:
     post-close refusal comes from there too (SPEC-032 FR-004) — a batch emitted after
     ``close()`` reaches ``send_all`` and is refused with ``SinkDeliveryError`` without the
     socket being reopened, so a guard here would only duplicate one that already holds.
+
+
+    It keeps **no** client buffer (SPEC-036 FR-002): each ``emit`` hands its bytes to the
+    socket before it returns, and no client object outlives it holding data. What the *network*
+    then does with a datagram is not something a flush could hurry.
     """
 
     def __init__(

{log_foundry-0.10.2.dev69 → log_foundry-0.10.2.dev71}/src/log_foundry/sinks/transform.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from log_foundry import _diag, _lifecycle
-from log_foundry.sinks.base import read_losses
+from log_foundry.sinks.base import flush_sink, read_losses
 
 if TYPE_CHECKING:
     import threading
@@ -27,6 +27,13 @@ class TransformSink:
     It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
     (SPEC-032 FR-003): it holds no transport and its ``close()`` only forwards, so both decisions
     belong to the inner sink. A guard here would refuse batches the inner sink would have taken.
+
+
+    It holds **no** client buffer of its own, but it **forwards** ``flush()`` to what it wraps
+    (SPEC-036 FR-002). Holding nothing is not the same as having nothing to do: a wrapper that
+    did not forward would leave a buffering child unreachable through ``log_foundry.flush()``
+    while looking fine — the SPEC-027 lesson about ``log_foundry_stop_signal``, that a signal
+    stopped at a wrapper reaches nothing and moves the defect rather than fixing it.
     """
 
     def __init__(
@@ -115,6 +122,25 @@ class TransformSink:
                 f"{type(self._inner).__name__} stays uninterruptible",
             )
 
+    def flush(self) -> None:
+        """Forwards the flush to the wrapped sink (SPEC-036 FR-002).
+
+        This wrapper holds nothing itself, but a wrapper that did not forward would leave a
+        buffering inner sink unreachable through ``log_foundry.flush()`` while looking fine —
+        the SPEC-027 lesson that a signal stopped at a wrapper reaches nothing.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          Exception: Whatever the wrapped sink raises, so the failure reaches the caller as a
+            ``FlushResult`` reason rather than being swallowed here.
+        """
+        flush_sink(self._inner)
+
     def losses(self) -> SinkLosses | None:
         """Reports the inner sink's losses (SPEC-026 FR-002).