log-foundry 0.10.2.dev16__tar.gz → 0.10.2.dev18__tar.gz

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev16
+Version: 0.10.2.dev18
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/pyproject.toml

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

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/_socket.py

@@ -15,6 +15,7 @@ import socket
 import time
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["SocketTransport"]
 
@@ -53,14 +54,35 @@ class SocketTransport:
         self._port = port
         self._transport = transport
         self._timeout = timeout
-        self._max_retries = max_retries
+        # Floored for the reason ``Worker._emit`` floors its own (SPEC-021): a negative value
+        # made no attempt at all and abandoned the message without moving ``failed``.
+        self._max_retries = max(max_retries, 0)
         self._sock: socket.socket | None = None
         self.failed = 0
 
     def send_all(self, messages: list[bytes]) -> None:
-        """Send each pre-framed message, reconnecting on error (FR-005, FR-006)."""
+        """Send each pre-framed message, reconnecting on error (FR-005, FR-006).
+
+        Raises :class:`~log_foundry.sinks.base.SinkDeliveryError` when **none** of the messages
+        reached the socket, so the sinks built on this transport propagate a dead destination to
+        the worker instead of reporting success (SPEC-026 FR-001). A partial send does not raise:
+        the worker's retry would re-send the messages that already landed.
+
+        An empty call is a no-op, not a total failure — ``delivered == 0`` there means there was
+        nothing to deliver.
+        """
+        delivered = 0
         for message in messages:
-            self._send_one(message)
+            if self._send_one(message):
+                delivered += 1
+        if messages and delivered == 0:
+            raise SinkDeliveryError(
+                f"SocketTransport delivered none of {len(messages)} message(s)"
+            )
+
+    def losses(self) -> SinkLosses:
+        """Messages abandoned past the reconnect-retry bound (SPEC-026 FR-002). Never raises."""
+        return SinkLosses(dropped=0, failed=self.failed)
 
     def close(self) -> None:
         """Close the held socket, if any; idempotent (FR-005, FR-012)."""
@@ -68,14 +90,15 @@ class SocketTransport:
 
     # -- internals ----------------------------------------------------------------------
 
-    def _send_one(self, message: bytes) -> None:
+    def _send_one(self, message: bytes) -> bool:
+        """Send one message within the retry bound; ``False`` once it is abandoned."""
         for attempt in range(self._max_retries + 1):
             try:
                 if self._transport == "udp":
                     self._socket().sendto(message, (self._host, self._port))
                 else:
                     self._socket().sendall(message)
-                return
+                return True
             except OSError as err:
                 self._reset()  # force a fresh connection on the next attempt
                 if attempt < self._max_retries:
@@ -92,7 +115,8 @@ class SocketTransport:
                     f"SocketTransport, {self._max_retries + 1} attempt(s), "
                     f"{type(err).__name__} {_diag.errno_of(err)}".rstrip(),
                 )
-                return
+                return False
+        return False  # unreachable: the loop returns on every path (mypy needs the exit)
 
     def _socket(self) -> socket.socket:
         if self._sock is None:

log_foundry-0.10.2.dev18/src/log_foundry/sinks/base.py

@@ -0,0 +1,119 @@
+"""The sink interface (arch §8).
+
+A sink is the swappable output transport. It receives *already-built, batched* event
+dicts from the worker and knows nothing about spans or context — that dumbness is what
+makes sinks trivially interchangeable (StdoutSink, SQSSink, …). Only the Protocol lives
+here; concrete sinks arrive in later phases.
+
+The interface carries two obligations beyond "put these somewhere" (SPEC-026), because the
+library's whole loss-reporting apparatus is built on them:
+
+* **Total failure raises.** A sink that delivered *none* of a batch must let something
+  propagate out of ``emit``. That is the signal the worker's bounded retry and
+  ``health().failed_batches`` are built on, and the one case where a retry cannot create
+  duplicates — nothing landed, so there is nothing downstream to duplicate.
+* **Partial failure does not.** A batch where some records landed must not be retried
+  wholesale; it is counted and made readable through the optional ``losses()``.
+
+A sink that absorbs a total failure and returns normally is a sink the worker believes:
+the retry never engages, ``failed_batches`` stays at zero and ``flush()`` returns ``True``
+while every event is lost. That reading is precisely what SPEC-017 existed to make
+impossible, and what SPEC-026 generalized from ``MultiSink`` to the whole family.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple, Protocol, runtime_checkable
+
+__all__ = ["Sink", "SinkDeliveryError", "SinkLosses", "read_losses"]
+
+
+class SinkDeliveryError(Exception):
+    """Raised by a sink whose ``emit`` delivered none of the batch (SPEC-026 FR-001).
+
+    A distinct type so an operator reading a ``stopped_reason`` or a diagnostic line can tell
+    "the destination refused everything" from "the sink itself has a bug". Sinks that already
+    have a natural exception to re-raise — a driver error, a ``MultiSink`` child's — re-raise
+    that instead: the contract is that *something* propagates, not that it must be this type.
+    """
+
+
+class SinkLosses(NamedTuple):
+    """What a sink discarded or could not confirm, cumulative for its lifetime (SPEC-026 FR-002).
+
+    Two fields rather than one because the remedies differ: ``dropped`` means the destination
+    could never have accepted the event as built (an oversized record), so the fix is upstream in
+    what the application logs; ``failed`` means delivery was attempted and the destination did not
+    confirm it, so the fix is the destination or the network.
+
+    ``failed`` is an **upper bound** on loss, not a count of it. A sink that also raises on total
+    failure counts the attempt here *and* hands the batch back to the worker, whose retry may
+    then deliver it — so a transient outage leaves ``failed`` non-zero with nothing actually
+    lost. ``health().failed_batches`` is the worker-level record of a batch given up on for good;
+    this is the sink-level record of everything that did not go through first time.
+    """
+
+    dropped: int
+    failed: int
+
+
+@runtime_checkable
+class Sink(Protocol):
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Ship a batch of serialized event dicts.
+
+        **Raise when the batch delivered nothing** and it was non-empty — the worker's bounded
+        retry and ``health().failed_batches`` depend on that signal, and a retry there cannot
+        duplicate anything (SPEC-026 FR-001). Raise *after* the sink's own retries are spent, so
+        the worker's retry composes on top rather than replacing it; a sink whose own budget
+        makes the worker's redundant should say so in its docstring rather than absorb silently.
+
+        **Do not raise on partial failure.** A batch where some records landed would be
+        re-delivered wholesale by the worker's retry, and duplicates downstream are worse than
+        the counted loss (SPEC-017 FR-004, SPEC-018). Report that through ``losses()`` instead.
+
+        ``emit([])`` is a no-op and never raises: an empty batch has not failed to deliver.
+        """
+        ...
+
+    def close(self) -> None:
+        """Flush and release any resources."""
+        ...
+
+    # ``losses()`` is optional, and deliberately *not* declared here: ``Sink`` is structural, and
+    # a third-party sink written against the pre-SPEC-026 interface must keep satisfying it.
+    # ``read_losses`` below is the probe; an absent method reads as "reports nothing".
+    #
+    #     def losses(self) -> SinkLosses | None:
+    #         """Cumulative loss this sink absorbed. Never raises; safe to call during emit.
+    #
+    #         ``None`` is the same answer as having no method at all — "this sink reports
+    #         nothing". A wrapper returns it when what it wraps reports nothing.
+    #         """
+    #         return SinkLosses(dropped=self._dropped, failed=self._failed)
+
+
+def read_losses(sink: object) -> SinkLosses | None:
+    """Read a sink's optional ``losses()``; ``None`` when it reports nothing.
+
+    ``None`` covers four cases deliberately treated alike: no ``losses`` attribute, one that is
+    not callable, one that raised, and one that returned anything other than a ``SinkLosses`` —
+    including ``None`` itself, which the shipped wrapper sinks return when what they wrap
+    reports nothing.
+
+    The single reader for the optional half of the protocol (SPEC-026 FR-002), shared by
+    ``Worker.health`` and ``MultiSink.losses`` so the probe and its guarantees are written once.
+
+    Total by design. ``health()`` is documented "Never raises" and is the call an operator makes
+    when things are *already* going wrong, so a third-party sink with a broken accessor must not
+    be able to take the snapshot down with it. The returned shape is checked as well as the call:
+    a ``losses()`` returning something else would otherwise put an arbitrary object where callers
+    read two integers. Nothing is written to stderr — a poll happens as often as the caller likes,
+    and a broken accessor is a sink bug rather than a loss.
+    """
+    try:
+        accessor = getattr(sink, "losses", None)
+        losses = accessor() if callable(accessor) else None
+    except Exception:
+        return None
+    return losses if isinstance(losses, SinkLosses) else None

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/clickhouse.py

@@ -14,6 +14,7 @@ from typing import Any
 
 from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["ClickHouseSink"]
 
@@ -54,7 +55,9 @@ class ClickHouseSink:
     ) -> None:
         self._table = valid_identifier(table)
         self._chunk_size = chunk_size
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_insert`` having attempted nothing, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self._closed = False
         self._owns_client = client is None
@@ -66,13 +69,25 @@ class ClickHouseSink:
         if create_table:
             self._ensure_schema()
 
+    def losses(self) -> SinkLosses:
+        """Rows in a chunk abandoned past the retry bound (SPEC-026 FR-002). Never raises."""
+        return SinkLosses(dropped=0, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Insert each chunk as one columnar ``insert`` call, retrying on failure (FR-002)."""
+        """Insert each chunk as one columnar ``insert`` call, retrying on failure (FR-002).
+
+        Raises when every chunk failed (SPEC-026 FR-001) — which is the whole batch for any
+        batch that fits one chunk, the ordinary case. A partially-inserted batch does not raise:
+        the chunks that landed are committed, and the worker's retry would duplicate them.
+        """
         if not batch:
             return
+        chunks = inserted = 0
         for chunk in chunk_list(batch, self._chunk_size):
-            rows = [self._row(event) for event in chunk]
-            self._insert(rows)
+            chunks += 1
+            inserted += self._insert([self._row(event) for event in chunk])
+        if chunks and not inserted:
+            raise SinkDeliveryError(f"ClickHouseSink inserted none of {chunks} chunk(s)")
 
     def close(self) -> None:
         """Close the client only if the sink owns it; idempotent (FR-005)."""
@@ -87,11 +102,12 @@ class ClickHouseSink:
     def _row(self, event: dict[str, object]) -> list[object]:
         return [*(event.get(col) for col in _COLUMNS), json.dumps(event)]
 
-    def _insert(self, rows: list[list[object]]) -> None:
+    def _insert(self, rows: list[list[object]]) -> int:
+        """Insert one chunk within the retry bound; ``1`` if it landed, ``0`` once abandoned."""
         for attempt in range(self.max_retries + 1):
             try:
                 self.client.insert(self._table, data=rows, column_names=_COLUMN_NAMES)
-                return
+                return 1
             except Exception as err:  # isolation boundary: never crash the worker (FR-006)
                 if attempt < self.max_retries:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
@@ -102,7 +118,8 @@ class ClickHouseSink:
                     len(rows),
                     f"ClickHouseSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
-                return
+                return 0
+        return 0  # unreachable: the loop returns on every path (mypy needs the exit)
 
     def _ensure_schema(self) -> None:
         columns = ", ".join(f"{col} {_COLUMN_TYPES[col]}" for col in _COLUMNS)

log_foundry-0.10.2.dev18/src/log_foundry/sinks/elasticsearch.py

@@ -0,0 +1,141 @@
+"""ElasticsearchSink / OpenSearchSink — index events via the ``_bulk`` API (arch §8, SPEC-009).
+
+A thin specialization of :class:`~log_foundry.sinks.http.HTTPSink`: each event becomes an action line
+(``{"index": {"_index": target}}``) followed by its source line, POSTed to ``_bulk`` as newline-
+delimited JSON. The bulk response is inspected per item so a partial failure is counted and logged
+without discarding the successfully-indexed items. OpenSearch speaks the same bulk protocol, so
+``OpenSearchSink`` is a straight reuse (endpoint/auth differ only by configuration).
+"""
+
+from __future__ import annotations
+
+import json
+
+from log_foundry import _diag
+from log_foundry.sinks._batch import usable_results
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry.sinks.http import HTTPSink
+
+__all__ = ["ElasticsearchSink", "OpenSearchSink"]
+
+
+class ElasticsearchSink(HTTPSink):
+    """POST events to an Elasticsearch ``_bulk`` endpoint, parsing per-item errors (FR-003).
+
+    Attributes:
+        item_errors: Count of bulk items the server reported as failed (distinct from ``failed``,
+            which counts whole requests abandoned past the retry bound).
+        dropped_unadjudicated: Events whose outcome a ``_bulk`` response did not describe — its
+            ``items`` array did not line up with the batch sent, so no event in it could be
+            paired to an outcome. Abandoned rather than retried, for SPEC-018's reason: the
+            request succeeded, so re-sending would duplicate whatever landed.
+    """
+
+    def __init__(self, url: str, *, index: str, auth: str | tuple[str, str] | None = None,
+                 **http_kwargs: object) -> None:
+        self._index = index
+        super().__init__(
+            url.rstrip("/") + "/_bulk", auth=auth, body_format="ndjson", **http_kwargs  # type: ignore[arg-type]
+        )
+        self.item_errors = 0
+        self.dropped_unadjudicated = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        """Build the ``_bulk`` NDJSON payload, POST it, and parse the response items (FR-003)."""
+        if not batch:
+            return
+        lines: list[str] = []
+        for event in batch:
+            lines.append(json.dumps({"index": {"_index": self._index}}))
+            lines.append(json.dumps(event))
+        body = ("\n".join(lines) + "\n").encode("utf-8")  # bulk must be newline-terminated
+        # An abandoned request raises out of ``_send`` now (SPEC-026 FR-001) — nothing was
+        # indexed, so there is no response to parse and nothing downstream to duplicate.
+        payload = self._send(body, content_type="application/x-ndjson")
+        if self._parse_bulk_response(payload, len(batch)):
+            # Every item carried an error, so the 200 indexed nothing: a total failure like any
+            # other, and it must reach the worker (FR-001). A retry cannot duplicate, and where
+            # the cause is permanent (a mapping conflict) the worker abandons the batch after
+            # its bound and records it — which beats a silent success. A response rejecting
+            # *some* items stays partial and is reported through ``losses()``.
+            raise SinkDeliveryError(
+                f"{type(self).__name__} indexed none of {len(batch)} event(s)"
+            )
+
+    def losses(self) -> SinkLosses:
+        """Abandoned requests plus server-rejected bulk items (SPEC-026 FR-002). Never raises.
+
+        All three are summed into ``failed`` because each is an event the server did not
+        confirm; they stay apart on the instance (``failed`` / ``item_errors`` /
+        ``dropped_unadjudicated``) for anyone who needs to tell "the request never landed" from
+        "the request landed and these items bounced" from "the response did not say".
+        """
+        return SinkLosses(
+            dropped=self.dropped_oversized,
+            failed=self.failed + self.item_errors + self.dropped_unadjudicated,
+        )
+
+    def _parse_bulk_response(self, payload: bytes, sent: int) -> bool:
+        """Count rejected items; return whether the response proves *nothing* was indexed.
+
+        The ``items`` array is positional — entry *i* describes event *i* — so the rule
+        ``sinks/_batch.py`` states applies here too (SPEC-018): a length disagreement is
+        evidence the arrays do not describe each other, not an invitation to read the overlap.
+        Counting errors does not depend on position, but concluding "all of them failed" does,
+        so that conclusion is gated on ``len(items) == sent``. Without the gate both directions
+        are wrong and both are reachable: a longer ``items`` array could make a partial success
+        raise (and the worker's retry would duplicate what landed), and a shorter one could
+        report a total failure as success.
+
+        Shape is adjudicated as well as length, through ``_batch.usable_results`` — the same
+        helper and the same reason: a list of non-mappings carries no per-record outcome that
+        can be read, so it describes nothing rather than describing success. And a body that
+        says ``errors: true`` while no entry yields a readable one contradicts itself, which is
+        the same "cannot tell" as a short array; reading it as "no items failed" is how a total
+        failure came back as success one level below the length check.
+
+        An array that cannot be adjudicated is counted on ``dropped_unadjudicated`` and left
+        alone — like ``KinesisSink``'s, the request itself succeeded, so re-sending it would
+        duplicate whatever did land. An unparseable or errors-free body returns ``False``: the
+        request succeeded, and a body this sink cannot read is not evidence against that.
+        """
+        try:
+            data = json.loads(payload)
+        except (ValueError, TypeError):
+            return False
+        if not isinstance(data, dict) or not data.get("errors"):
+            return False
+        items = usable_results(data.get("items"))
+        errors = sum(1 for item in items if _has_error(item))
+        if len(items) != sent or not errors:
+            # ``not errors`` is unadjudicable rather than clean *because* the server said
+            # ``errors: true``: the two disagree, and this sink is the one that cannot read the
+            # answer. An errors-free response never reaches here — it returned above.
+            self.dropped_unadjudicated += sent
+            _diag.lost(
+                "event",
+                sent,
+                f"{type(self).__name__} could not adjudicate a _bulk response "
+                f"({sent} event(s) sent, {len(items)} readable item(s), {errors} error(s)); "
+                f"not retried",
+            )
+            return False
+        # Unconditional only because the gate above already returned on ``not errors``; a
+        # loosened gate would start writing "lost 0 bulk item(s)" here.
+        self.item_errors += errors
+        _diag.lost("bulk item", errors, f"{type(self).__name__}, rejected by the server")
+        return errors == sent
+
+
+def _has_error(item: dict[str, object]) -> bool:
+    """Whether a ``_bulk`` item reports a failure under *any* of its action keys.
+
+    Every value is examined, not just the first: a real response carries one key per item, but
+    reading only ``next(iter(...))`` would score an item whose error sits under a second key as
+    a success — and a miscounted success is what turns a total failure into a partial one.
+    """
+    return any(isinstance(result, dict) and result.get("error") for result in item.values())
+
+
+class OpenSearchSink(ElasticsearchSink):
+    """OpenSearch reuses the Elasticsearch ``_bulk`` protocol verbatim (FR-003)."""

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/eventhubs.py

@@ -14,6 +14,7 @@ import time
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["AzureEventHubsSink"]
 
@@ -44,27 +45,52 @@ class AzureEventHubsSink:
                 connection_str, eventhub_name=eventhub
             )
         self.producer = producer
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_send`` having attempted nothing, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self.dropped_oversized = 0
 
+    def losses(self) -> SinkLosses:
+        """Oversized drops and events in a batch abandoned past the retry bound (FR-002)."""
+        return SinkLosses(dropped=self.dropped_oversized, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Pack events into ≤ 1 MB EventDataBatches and send each; drop oversized events (FR-009)."""
+        """Pack events into ≤ 1 MB EventDataBatches and send each; drop oversized events (FR-009).
+
+        Raises when every ``EventDataBatch`` failed to send and at least one was attempted
+        (SPEC-026 FR-001). An event dropped for being too large is not a send failure — it can
+        never fit, so a batch of nothing but oversized events has nothing to retry and does not
+        raise; it is reported through ``losses().dropped`` instead.
+        """
         if not batch:
             return
         event_data_cls = _event_data_cls()
         current = self.producer.create_batch()
+        attempted = delivered = 0
         for event in batch:
             data = event_data_cls(json.dumps(event).encode("utf-8"))
             if _try_add(current, data):
                 continue
-            # current batch is full: send it and start a fresh one for this event.
-            self._send(current)
+            # current batch is full: send it and start a fresh one for this event. Guarded on
+            # emptiness because ``_try_add`` also fails against a *fresh* batch when the event
+            # is oversized, and the SDK short-circuits ``send_batch`` on an empty batch and
+            # returns — a phantom success that counted as delivery and suppressed the raise for
+            # everything else in the emit.
+            if len(current) > 0:
+                attempted += 1
+                delivered += self._send(current)
             current = self.producer.create_batch()
             if not _try_add(current, data):
                 self.dropped_oversized += 1
                 _diag.lost("event", 1, "AzureEventHubsSink, too large for an empty 1 MB batch")
-        self._send(current)
+        if len(current) > 0:
+            attempted += 1
+            delivered += self._send(current)
+        if attempted and not delivered:
+            raise SinkDeliveryError(
+                f"AzureEventHubsSink sent none of {attempted} EventDataBatch(es)"
+            )
 
     def close(self) -> None:
         """Close the producer (FR-009)."""
@@ -72,14 +98,18 @@ class AzureEventHubsSink:
 
     # -- internals ----------------------------------------------------------------------
 
-    def _send(self, event_batch: Any) -> None:
-        """Send one EventDataBatch (skipping an empty one), retrying failures (FR-009, FR-011)."""
-        if len(event_batch) == 0:
-            return
+    def _send(self, event_batch: Any) -> int:
+        """Send one EventDataBatch, retrying failures; ``1`` if it landed (FR-009, FR-011).
+
+        Callers only reach this with a non-empty batch — both call sites check — and count the
+        result: the "did anything land" question in ``emit`` cannot be answered by a method that
+        returns nothing. An empty one must never be sent: the SDK returns immediately without
+        contacting the hub, which would score as a delivery nobody made.
+        """
         for attempt in range(self.max_retries + 1):
             try:
                 self.producer.send_batch(event_batch)
-                return
+                return 1
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 if attempt < self.max_retries:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
@@ -91,7 +121,8 @@ class AzureEventHubsSink:
                     f"AzureEventHubsSink, one batch, {self.max_retries + 1} attempts, "
                     f"{type(err).__name__}",
                 )
-                return
+                return 0
+        return 0  # unreachable: the loop returns on every path (mypy needs the exit)
 
 
 def _try_add(event_batch: Any, data: Any) -> bool:

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/filtering.py

@@ -10,10 +10,12 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from log_foundry.sinks.base import read_losses
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from log_foundry.sinks.base import Sink
+    from log_foundry.sinks.base import Sink, SinkLosses
 
 __all__ = ["FilteringSink"]
 
@@ -69,6 +71,20 @@ class FilteringSink:
                 return False
         return True
 
+    def losses(self) -> SinkLosses | None:
+        """Report the inner sink's losses (SPEC-026 FR-002). Never raises.
+
+        A wrapper that reported nothing would hide the destination it wraps: ``health().sink``
+        would read ``None`` for a ``FilteringSink`` in front of a sink that counts perfectly well.
+        Events this sink itself declines to forward are not loss — they are the configuration
+        working, the same reason ``NullSink`` reports nothing.
+
+        ``None`` passes through unchanged rather than becoming ``SinkLosses(0, 0)``: FR-003
+        distinguishes "the sink reports nothing" from "the sink reports no loss", and a wrapper
+        that flattened the two would claim a clean bill of health on a sink that never gave one.
+        """
+        return read_losses(self._inner)
+
     def close(self) -> None:
         """Close the inner sink (FR-003)."""
         self._inner.close()