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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev16
+Version: 0.10.2.dev17
 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.dev17}/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.dev17"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/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.dev17/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.dev17/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.dev17}/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()

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/http.py

@@ -19,9 +19,10 @@ import time
 import urllib.error
 import urllib.request
 from base64 import b64encode
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NoReturn
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -77,7 +78,10 @@ class HTTPSink:
         self.body_format = body_format
         self.timeout = timeout
         self.gzip = gzip
-        self.max_retries = max_retries
+        # Floored, as ``Worker._emit`` floors its own (SPEC-021): a negative value otherwise
+        # skipped the loop entirely, so the request was abandoned with no attempt made and no
+        # counter moved — reachable only by misconfiguration, but reachable.
+        self.max_retries = max(max_retries, 0)
         self._opener = opener if opener is not None else urllib.request.urlopen
         self.failed = 0
         self.dropped_oversized = 0
@@ -89,6 +93,15 @@ class HTTPSink:
         body, content_type = self._encode(batch)
         self._send(body, content_type=content_type)
 
+    def losses(self) -> SinkLosses:
+        """Oversized drops and abandoned requests (SPEC-026 FR-002). Never raises.
+
+        ``failed`` counts abandoned *requests*, not events — this class has no per-event outcome
+        to report, and an abandoned request took its whole body with it. Subclasses that do learn
+        per-record outcomes (``ElasticsearchSink``) add them.
+        """
+        return SinkLosses(dropped=self.dropped_oversized, failed=self.failed)
+
     def close(self) -> None:
         """No-op — ``urllib`` opens a fresh connection per request; idempotent (FR-012)."""
 
@@ -109,11 +122,20 @@ class HTTPSink:
         *,
         content_type: str,
         extra_headers: dict[str, str] | None = None,
-    ) -> bytes | None:
-        """POST ``body`` with bounded retry; return the response bytes, or ``None`` if abandoned.
+    ) -> bytes:
+        """POST ``body`` with bounded retry; return the response bytes.
 
         Subclasses that must inspect the response (e.g. Elasticsearch ``_bulk`` ``items``) use the
-        returned bytes; a ``None`` return means the request was retried to exhaustion and counted.
+        returned bytes. A request retried to exhaustion is counted and then **raises**
+        :class:`~log_foundry.sinks.base.SinkDeliveryError` (SPEC-026 FR-001) — it used to return
+        ``None``, which every caller here spelled as "nothing to parse" and the worker read as a
+        successful emit. One request carries the whole batch, so an abandoned one delivered
+        nothing and is exactly the total failure the worker's retry exists for.
+
+        Raising from here rather than from each ``emit`` is deliberate: every platform subclass
+        (Datadog, Splunk, New Relic, Honeycomb, Loki, Logstash-HTTP) builds its own body and calls
+        this, so the rule reaches them without a line of their own. The one caller that must not
+        propagate is ``SentrySink``, which sends one envelope *per event* and therefore catches it.
         """
         headers, data = self._prepare(body, content_type, extra_headers)
         for attempt in range(self.max_retries + 1):
@@ -134,15 +156,14 @@ class HTTPSink:
                 self._abandon(
                     f"connection error, {type(err).__name__} {_diag.errno_of(err)}".rstrip()
                 )
-                return None
             if 200 <= status < 300:
                 return payload
             if (status == 429 or 500 <= status < 600) and attempt < self.max_retries:
                 self._sleep_backoff(attempt, retry_after)
                 continue
             self._abandon(f"HTTP {status}")
-            return None
-        return None
+        # Unreachable: every path through the loop returns or raises. mypy needs the exit.
+        raise SinkDeliveryError(f"{type(self).__name__} made no attempt")
 
     def _prepare(
         self,
@@ -202,16 +223,22 @@ class HTTPSink:
         delay = retry_after if retry_after is not None else _BACKOFF_BASE * (2**attempt)
         time.sleep(delay)
 
-    def _abandon(self, reason: str) -> None:
-        """Count and log a request abandoned past the retry bound (FR-012).
+    def _abandon(self, reason: str) -> NoReturn:
+        """Count, log, then raise for a request abandoned past the retry bound (FR-012).
 
         ``reason`` carries only library-controlled values — an HTTP status, an exception type, an
-        ``errno`` — never a server-supplied body or an exception's text (SPEC-029 FR-002).
+        ``errno`` — never a server-supplied body or an exception's text (SPEC-029 FR-002). It is
+        also the message of the raised error, for the same reason.
+
+        The counter moves *before* the raise: ``failed`` is this sink's own record of what it
+        could not put on the wire, and it must not depend on who catches what. It therefore
+        counts every worker retry attempt too, so it is an upper bound on loss rather than a
+        count of it — see :class:`~log_foundry.sinks.base.SinkLosses`.
         """
         self.failed += 1
-        _diag.lost(
-            "request", 1, f"{type(self).__name__}, {self.max_retries + 1} attempt(s), {reason}"
-        )
+        detail = f"{type(self).__name__}, {self.max_retries + 1} attempt(s), {reason}"
+        _diag.lost("request", 1, detail)
+        raise SinkDeliveryError(detail)
 
 
 def _parse_retry_after(headers: Any) -> float | None:

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/logstash.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import json
 
 from log_foundry.sinks._socket import SocketTransport
+from log_foundry.sinks.base import SinkLosses
 from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["LogstashSink"]
@@ -73,3 +74,15 @@ class LogstashSink:
         return self._http.failed if self._http is not None else (
             self._socket.failed if self._socket is not None else 0
         )
+
+    def losses(self) -> SinkLosses:
+        """Delegate to whichever backend is held (SPEC-026 FR-002). Never raises.
+
+        Both backends raise on total failure of their own accord, so ``emit`` needs no rule of
+        its own — it forwards the whole batch to exactly one of them.
+        """
+        if self._http is not None:
+            return self._http.losses()
+        if self._socket is not None:
+            return self._socket.losses()
+        return SinkLosses(dropped=0, failed=0)  # unreachable: __init__ sets exactly one

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/multi.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkLosses, read_losses
 
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
@@ -73,6 +74,32 @@ class MultiSink:
             # misconfigured fan-out with no children would retry every batch to exhaustion.
             raise first_error
 
+    def losses(self) -> SinkLosses | None:
+        """Sum the children's losses so a fan-out reports the whole tree (SPEC-026 FR-002).
+
+        Never raises: a child without ``losses()`` contributes zero, and a child whose accessor
+        raises or returns the wrong shape is skipped rather than allowed to take the aggregate —
+        and ``health()`` with it — down. Nesting is handled for free, since a child ``MultiSink``
+        is just another sink with a ``losses()``.
+
+        ``MultiSink.failed`` is deliberately absent from the total. It counts child *calls* that
+        raised, not events, so adding it to a per-event figure would produce a number with no
+        unit. The children already report their own loss in events.
+
+        ``None`` when *no* child reported anything — including an empty fan-out. FR-003 separates
+        "reports nothing" from "reports no loss", and a tree of silent children has not given a
+        clean bill of health; summing them to zero would claim one on their behalf. One reporting
+        child is enough to make the total meaningful, since the silent ones contribute zero.
+        """
+        children = [read_losses(sink) for sink in self._sinks]
+        reported = [child for child in children if child is not None]
+        if not reported:
+            return None
+        return SinkLosses(
+            dropped=sum(child.dropped for child in reported),
+            failed=sum(child.failed for child in reported),
+        )
+
     def close(self) -> None:
         """Close every child, isolating a failing child so the rest still close (FR-002)."""
         for sink in self._sinks:

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/sentry.py

@@ -14,6 +14,8 @@ import uuid
 from typing import Any
 from urllib.parse import urlparse
 
+from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["SentrySink"]
@@ -32,6 +34,8 @@ class SentrySink:
     Attributes:
         sent: Events captured/sent to Sentry.
         skipped: Events below ``min_level`` (or without a usable level) that were not sent.
+        transport_errors: Events whose send raised something other than an already-counted
+            abandonment — an SDK fault, or a response error ``HTTPSink`` does not retry.
     """
 
     def __init__(
@@ -47,6 +51,7 @@ class SentrySink:
         self._min_rank = _LEVEL_RANK.get(min_level.upper(), _LEVEL_RANK["ERROR"])
         self.sent = 0
         self.skipped = 0
+        self.transport_errors = 0
         self._sdk = sdk if sdk is not None else _import_sdk()
         self._http: HTTPSink | None = None
         self._auth_header = ""
@@ -60,16 +65,30 @@ class SentrySink:
             self._http = HTTPSink(ingest_url, opener=opener, max_retries=max_retries)
 
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Capture each qualifying event via the SDK or the HTTP fallback (FR-011)."""
+        """Capture each qualifying event via the SDK or the HTTP fallback (FR-011).
+
+        One envelope per event, so an abandoned request is a *per-event* outcome: it is caught,
+        counted, and only re-raised when the whole batch got through to nothing (SPEC-026
+        FR-001). Letting the first failure propagate would hand the worker a batch whose earlier
+        events Sentry had already accepted, and the retry would duplicate them.
+
+        An event below ``min_level`` is skipped, not lost, so a batch of nothing but skipped
+        events is a successful emit — there was never anything to deliver.
+        """
+        attempted = delivered = 0
         for event in batch:
             if not self._qualifies(event):
                 self.skipped += 1
                 continue
-            if self._sdk is not None:
-                self._sdk.capture_event(self._sentry_event(event))
-            else:
-                self._post_envelope(event)
+            attempted += 1
+            if not self._capture(event):
+                continue
             self.sent += 1
+            delivered += 1
+        if attempted and not delivered:
+            raise SinkDeliveryError(
+                f"SentrySink delivered none of {attempted} qualifying event(s)"
+            )
 
     def close(self) -> None:
         """Release the HTTP fallback resource, if any; idempotent (FR-012)."""
@@ -81,8 +100,48 @@ class SentrySink:
         """Requests abandoned past the retry bound (HTTP fallback only)."""
         return self._http.failed if self._http is not None else 0
 
+    def losses(self) -> SinkLosses:
+        """Envelopes abandoned past the retry bound (SPEC-026 FR-002). Never raises.
+
+        ``skipped`` is deliberately **not** ``dropped``: an event below ``min_level`` was never
+        meant for Sentry, and reporting a configured filter as loss would make the alert idiom
+        fire on every INFO log. What *is* reported is an abandoned envelope (``failed``, counted
+        by ``HTTPSink``) and an event whose send raised (``transport_errors``) — on either
+        transport. Delivery the SDK accepts and then loses internally is the SDK's to report.
+        """
+        return SinkLosses(dropped=0, failed=self.failed + self.transport_errors)
+
     # -- internals ----------------------------------------------------------------------
 
+    def _capture(self, event: dict[str, object]) -> bool:
+        """Send one event by whichever transport is configured; ``False`` if it did not land.
+
+        One guard over **both** branches, catching ``Exception`` rather than an enumerated set.
+        Anything escaping here propagates mid-batch and hands the worker a batch Sentry has
+        already accepted the earlier events of, and the retry duplicates them — the failure this
+        per-event design exists to prevent. Enumerating was tried and was wrong twice over: the
+        SDK branch is third-party code that can raise anything, and ``HTTPSink._send`` catches
+        ``(URLError, OSError)``, which does **not** cover ``http.client.HTTPException`` — an
+        ``IncompleteRead`` off ``response.read()`` came straight through. A caller-injected
+        ``opener`` widens that further, since it is arbitrary code too.
+
+        ``SinkDeliveryError`` is caught separately only because ``HTTPSink._abandon`` has already
+        counted and announced it; counting it again here would double-report. Only the exception
+        type is ever written (arch §6).
+        """
+        try:
+            if self._sdk is not None:
+                self._sdk.capture_event(self._sentry_event(event))
+            else:
+                self._post_envelope(event)
+        except SinkDeliveryError:
+            return False  # already counted and logged by HTTPSink._abandon
+        except Exception as err:  # isolation boundary: one event must not fail the batch
+            self.transport_errors += 1
+            _diag.lost("event", 1, f"SentrySink, {type(err).__name__}")
+            return False
+        return True
+
     def _qualifies(self, event: dict[str, object]) -> bool:
         level = event.get("level")
         if not isinstance(level, str):

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/syslog.py

@@ -11,9 +11,13 @@ from __future__ import annotations
 import json
 import os
 import socket
+from typing import TYPE_CHECKING
 
 from log_foundry.sinks._socket import SocketTransport
 
+if TYPE_CHECKING:
+    from log_foundry.sinks.base import SinkLosses
+
 __all__ = ["SyslogSink"]
 
 # RFC 5424 numeric severities; log-foundry levels mapped onto them (unknown level -> notice/5).
@@ -69,6 +73,15 @@ class SyslogSink:
         """Messages abandoned past the retry bound."""
         return self._socket.failed
 
+    def losses(self) -> SinkLosses:
+        """Delegate to the socket transport (SPEC-026 FR-002). Never raises.
+
+        The transport raises on total failure, and ``emit`` hands it the whole batch in one
+        call, so a dead syslog destination now reaches ``health().failed_batches`` — the reading
+        SPEC-026 was written from, where ``flush()`` returned ``True`` and every frame was lost.
+        """
+        return self._socket.losses()
+
     # -- internals ----------------------------------------------------------------------
 
     def _frame(self, event: dict[str, object]) -> bytes:

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/transform.py

@@ -11,10 +11,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__ = ["TransformSink"]
 
@@ -44,6 +46,20 @@ class TransformSink:
         if transformed:
             self._inner.emit(transformed)
 
+    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 ``TransformSink`` 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-004)."""
         self._inner.close()

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/sinks/util.py

@@ -32,6 +32,10 @@ class NullSink:
 
     Useful to disable output without unwiring the pipeline, or to benchmark everything up to the
     sink. ``dropped`` counts how many events were discarded, so a benchmark can assert throughput.
+
+    Deliberately exposes no ``losses()`` (SPEC-026 FR-002): discarding is what this sink is *for*,
+    and reporting it as loss would make ``health()``'s alert idiom fire on every batch for anyone
+    who chose this sink to turn logging off. The counter stays readable on the instance.
     """
 
     def __init__(self) -> None:

{log_foundry-0.10.2.dev16 → log_foundry-0.10.2.dev17}/src/log_foundry/worker.py

@@ -27,7 +27,7 @@ from typing import TYPE_CHECKING, NamedTuple, cast
 from log_foundry import _diag
 
 if TYPE_CHECKING:
-    from log_foundry.sinks.base import Sink
+    from log_foundry.sinks.base import Sink, SinkLosses
 
 __all__ = ["Health", "Worker"]
 
@@ -54,6 +54,11 @@ class Health(NamedTuple):
             logged report. Non-``None`` is categorically worse than the two counters above:
             they measure loss the worker absorbed and kept running through, this one means
             the worker is gone and nothing further will be delivered (SPEC-019 FR-003).
+        sink: The configured sink's own loss counters, or ``None`` when there is no worker or
+            the sink reports nothing (SPEC-026 FR-003). Nested rather than folded into the two
+            integers above because they mean different things: ``dropped`` here is backpressure
+            at the queue, ``dropped`` on the sink is an event the destination could never
+            accept, and one number would make the remedies indistinguishable.
     """
 
     queued: int
@@ -62,6 +67,9 @@ class Health(NamedTuple):
     # Defaulted so the zeroed snapshot in `decorator._worker_health` — and any third-party
     # construction — keeps working unchanged.
     stopped_reason: str | None = None
+    # Appended for the same reason `stopped_reason` was: attribute and index access to every
+    # field that came before stay exactly as they were.
+    sink: SinkLosses | None = None
 
 
 class _FlushMarker:
@@ -179,8 +187,20 @@ class Worker:
             dropped=dropped,
             failed_batches=failed_batches,
             stopped_reason=stopped_reason,
+            sink=self._sink_losses(),
         )
 
+    def _sink_losses(self) -> SinkLosses | None:
+        """Read the configured sink's optional ``losses()``; ``None`` when it has none (FR-003).
+
+        The probe and its guarantees live in ``sinks.base.read_losses`` — imported here rather
+        than at module scope, keeping ``worker`` free of a runtime dependency on ``sinks`` the
+        same way ``config`` does (the ``Sink`` Protocol itself is ``TYPE_CHECKING``-only).
+        """
+        from log_foundry.sinks.base import read_losses
+
+        return read_losses(self.sink)
+
     def flush(self, timeout: float | None = 5.0) -> bool:
         """Drain everything submitted before this call through the sink, without stopping.
 

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

@@ -1,22 +0,0 @@
-"""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.
-"""
-
-from __future__ import annotations
-
-from typing import Protocol, runtime_checkable
-
-
-@runtime_checkable
-class Sink(Protocol):
-    def emit(self, batch: list[dict[str, object]]) -> None:
-        """Ship a batch of serialized event dicts."""
-        ...
-
-    def close(self) -> None:
-        """Flush and release any resources."""
-        ...

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

@@ -1,68 +0,0 @@
-"""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.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).
-    """
-
-    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
-
-    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
-        payload = self._send(body, content_type="application/x-ndjson")
-        if payload is not None:
-            self._parse_bulk_response(payload)
-
-    def _parse_bulk_response(self, payload: bytes) -> None:
-        """Count items the bulk response flagged as errors; a partial failure keeps the rest."""
-        try:
-            data = json.loads(payload)
-        except (ValueError, TypeError):
-            return
-        if not isinstance(data, dict) or not data.get("errors"):
-            return
-        errors = 0
-        for item in data.get("items", []):
-            result: object = next(iter(item.values()), {}) if isinstance(item, dict) else {}
-            if isinstance(result, dict) and result.get("error"):
-                errors += 1
-        if errors:
-            self.item_errors += errors
-            _diag.lost("bulk item", errors, f"{type(self).__name__}, rejected by the server")
-
-
-class OpenSearchSink(ElasticsearchSink):
-    """OpenSearch reuses the Elasticsearch ``_bulk`` protocol verbatim (FR-003)."""