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

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

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

{log_foundry-0.10.2.dev17 → 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.dev17 → 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.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/firehose.py

@@ -14,6 +14,7 @@ from typing import Any
 from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["FirehoseSink"]
 
@@ -41,21 +42,62 @@ class FirehoseSink:
             client = boto3.client("firehose")
         self.delivery_stream = delivery_stream
         self.client = client
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_send`` having sent nothing, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
 
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Re-chunk to put_record_batch limits and send each chunk, retrying failures (FR-004)."""
+        """Re-chunk to put_record_batch limits and send each chunk, retrying failures (FR-004).
+
+        Raises when every chunk failed and at least one was sent (SPEC-026 FR-001). Records
+        dropped before sending — too large to ever fit — are not a send failure and do not make
+        a batch of nothing but oversized records raise; they can never be retried into
+        existence, and are reported through ``losses().dropped``.
+
+        An unadjudicable chunk is *unknown*, not *nothing*, and suppresses the raise. SPEC-018
+        settled that such a chunk is abandoned rather than re-sent — the API reported a failure
+        count, so some of it landed, and the worker's retry would duplicate that downstream
+        forever. Raising on it would be exactly the re-send SPEC-018 refuses.
+
+        That suppression is batch-wide, unlike ``SQSSink``'s. A sender fault is a rejection —
+        the entries provably did not land, so re-sending them is futile rather than harmful —
+        while "unadjudicable" means this sink *cannot tell* whether they landed. Once any chunk
+        is in that state the emit can no longer prove nothing was delivered, so a raise would
+        risk duplicating it, and the events in a plainly-failed sibling chunk stay a counted
+        loss rather than a duplicated delivery. SPEC-018 chose that trade once already.
+        """
         records = self._records(batch)
+        chunks = delivered = 0
+        unknown = False
         for chunk in chunk_items(
             records,
             max_count=self.MAX_RECORDS,
             max_bytes=self.MAX_REQUEST_BYTES,
             size_of=lambda record: len(record["Data"]),
         ):
-            self._send(chunk)
+            chunks += 1
+            outcome = self._send(chunk)
+            if outcome is None:
+                unknown = True
+            else:
+                delivered += outcome
+        if chunks and not delivered and not unknown:
+            raise SinkDeliveryError(f"FirehoseSink delivered none of {chunks} chunk(s)")
+
+    def losses(self) -> SinkLosses:
+        """Oversized drops, abandoned records and unadjudicable chunks (FR-002). Never raises.
+
+        ``failed`` sums ``failed`` and ``dropped_unadjudicated``: both are records the stream
+        never confirmed. They stay apart on the instance, because "the stream said these failed"
+        and "the response did not describe them" have different remedies (SPEC-018).
+        """
+        return SinkLosses(
+            dropped=self.dropped_oversized,
+            failed=self.failed + self.dropped_unadjudicated,
+        )
 
     def close(self) -> None:
         """No-op: the sink buffers nothing internally (FR-001)."""
@@ -79,14 +121,23 @@ class FirehoseSink:
             records.append({"Data": data})
         return records
 
-    def _send(self, records: list[dict[str, Any]]) -> None:
-        """Send one chunk, retrying only the entries the response flags as failed (FR-004)."""
+
+    def _send(self, records: list[dict[str, Any]]) -> int | None:
+        """Send one chunk, retrying only the entries the response flags as failed (FR-004).
+
+        Returns how many records the stream accepted, so ``emit`` can tell "nothing landed"
+        from a partial success — or ``None`` when the response could not be adjudicated, which
+        is neither. "The stream did not say" must not be read as "the stream took nothing":
+        that reading would make ``emit`` raise, and the worker's retry would re-send a chunk
+        SPEC-018 settled must never be re-sent.
+        """
+        sent = len(records)
         for attempt in range(self.max_retries + 1):
             response = self.client.put_record_batch(
                 DeliveryStreamName=self.delivery_stream, Records=records
             )
             if not response.get("FailedPutCount"):
-                return
+                return sent
             results = usable_results(response.get("RequestResponses"))
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
@@ -98,10 +149,10 @@ class FirehoseSink:
                     f"({len(records)} record(s) sent, {len(results)} result(s) returned); "
                     f"abandoned, not retried",
                 )
-                return
+                return None
             records = verdict.retry
             if not records:
-                return
+                return sent
             if attempt >= self.max_retries:
                 self.failed += len(records)
                 _diag.lost(
@@ -109,4 +160,5 @@ class FirehoseSink:
                     len(records),
                     f"FirehoseSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
-                return
+                return sent - len(records)
+        return 0  # unreachable: the loop returns on every path (mypy needs the exit)

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/kafka.py

@@ -13,6 +13,7 @@ import json
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["KafkaSink"]
 
@@ -22,6 +23,8 @@ class KafkaSink:
 
     Attributes:
         failed: Messages whose delivery callback reported an error.
+        rejected: Messages ``produce()`` itself refused — a full local queue, a serialization
+            fault — which never reached the producer's batch at all.
     """
 
     def __init__(
@@ -44,14 +47,45 @@ class KafkaSink:
         self.producer = producer
         self.key_field = key_field
         self.failed = 0
+        self.rejected = 0
+
+    def losses(self) -> SinkLosses:
+        """Refused and undelivered messages (SPEC-026 FR-002). Never raises.
+
+        ``rejected`` is ``dropped``: ``produce()`` refused it, so nothing ever left the process.
+        ``failed`` is the delivery callback's verdict on a message the producer *did* accept.
+
+        A callback failure never makes ``emit`` raise, and the reason is ownership rather than
+        timing — ``poll(0)`` runs inside ``emit``, so a callback for a message produced earlier
+        in the same batch can and does fire before it returns. Once the producer has accepted a
+        message it owns delivery, including its own retries; re-producing it from here would
+        duplicate whatever the producer eventually lands. So the raise decision reads only what
+        ``produce()`` refused.
+        """
+        return SinkLosses(dropped=self.rejected, failed=self.failed)
 
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Produce one message per event; serve delivery callbacks without blocking (FR-002)."""
+        """Produce one message per event; serve delivery callbacks without blocking (FR-002).
+
+        ``produce()`` is a local hand-off, so what it refuses is the only failure this call can
+        observe. When it refused *every* message the batch reached nothing, which is the total
+        failure the worker's retry exists for (SPEC-026 FR-001); a partial refusal is counted and
+        left alone, since the messages that were accepted are already on their way.
+        """
+        accepted = 0
         for event in batch:
             body = json.dumps(event).encode("utf-8")
             key = self._key(event)
-            self.producer.produce(self.topic, value=body, key=key, callback=self._on_delivery)
+            try:
+                self.producer.produce(self.topic, value=body, key=key, callback=self._on_delivery)
+            except Exception as err:  # BufferError on a full local queue, and anything the
+                self.rejected += 1    # driver raises for an unproducible message
+                _diag.lost("message", 1, f"KafkaSink produce, {type(err).__name__}")
+                continue
+            accepted += 1
             self.producer.poll(0)  # serve queued delivery callbacks, non-blocking
+        if batch and not accepted:
+            raise SinkDeliveryError(f"KafkaSink produced none of {len(batch)} message(s)")
 
     def close(self) -> None:
         """Flush the producer so buffered messages are delivered before exit (FR-002)."""

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/kinesis.py

@@ -15,6 +15,7 @@ from typing import Any
 from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["KinesisSink"]
 
@@ -49,21 +50,62 @@ class KinesisSink:
         self.stream_name = stream_name
         self.client = client
         self.partition_key_field = partition_key_field
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_send`` having sent nothing, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
 
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Re-chunk to put_records limits and send each chunk, retrying failures (FR-003)."""
+        """Re-chunk to put_records limits and send each chunk, retrying failures (FR-003).
+
+        Raises when every chunk failed and at least one was sent (SPEC-026 FR-001). Records
+        dropped before sending — too large to ever fit — are not a send failure and do not make
+        a batch of nothing but oversized records raise; they can never be retried into
+        existence, and are reported through ``losses().dropped``.
+
+        An unadjudicable chunk is *unknown*, not *nothing*, and suppresses the raise. SPEC-018
+        settled that such a chunk is abandoned rather than re-sent — the API reported a failure
+        count, so some of it landed, and the worker's retry would duplicate that downstream
+        forever. Raising on it would be exactly the re-send SPEC-018 refuses.
+
+        That suppression is batch-wide, unlike ``SQSSink``'s. A sender fault is a rejection —
+        the entries provably did not land, so re-sending them is futile rather than harmful —
+        while "unadjudicable" means this sink *cannot tell* whether they landed. Once any chunk
+        is in that state the emit can no longer prove nothing was delivered, so a raise would
+        risk duplicating it, and the events in a plainly-failed sibling chunk stay a counted
+        loss rather than a duplicated delivery. SPEC-018 chose that trade once already.
+        """
         records = self._records(batch)
+        chunks = delivered = 0
+        unknown = False
         for chunk in chunk_items(
             records,
             max_count=self.MAX_RECORDS,
             max_bytes=self.MAX_REQUEST_BYTES,
             size_of=lambda record: len(record["Data"]),
         ):
-            self._send(chunk)
+            chunks += 1
+            outcome = self._send(chunk)
+            if outcome is None:
+                unknown = True
+            else:
+                delivered += outcome
+        if chunks and not delivered and not unknown:
+            raise SinkDeliveryError(f"KinesisSink delivered none of {chunks} chunk(s)")
+
+    def losses(self) -> SinkLosses:
+        """Oversized drops, abandoned records and unadjudicable chunks (FR-002). Never raises.
+
+        ``failed`` sums ``failed`` and ``dropped_unadjudicated``: both are records the stream
+        never confirmed. They stay apart on the instance, because "the stream said these failed"
+        and "the response did not describe them" have different remedies (SPEC-018).
+        """
+        return SinkLosses(
+            dropped=self.dropped_oversized,
+            failed=self.failed + self.dropped_unadjudicated,
+        )
 
     def close(self) -> None:
         """No-op: the sink buffers nothing internally (FR-001)."""
@@ -88,12 +130,20 @@ class KinesisSink:
             records.append({"Data": data, "PartitionKey": key})
         return records
 
-    def _send(self, records: list[dict[str, Any]]) -> None:
-        """Send one chunk, retrying only the records the response flags as failed (FR-003)."""
+    def _send(self, records: list[dict[str, Any]]) -> int | None:
+        """Send one chunk, retrying only the records the response flags as failed (FR-003).
+
+        Returns how many records the stream accepted, so ``emit`` can tell "nothing landed"
+        from a partial success — or ``None`` when the response could not be adjudicated, which
+        is neither. "The stream did not say" must not be read as "the stream took nothing":
+        that reading would make ``emit`` raise, and the worker's retry would re-send a chunk
+        SPEC-018 settled must never be re-sent.
+        """
+        sent = len(records)
         for attempt in range(self.max_retries + 1):
             response = self.client.put_records(StreamName=self.stream_name, Records=records)
             if not response.get("FailedRecordCount"):
-                return
+                return sent
             results = usable_results(response.get("Records"))
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
@@ -104,10 +154,10 @@ class KinesisSink:
                     f"KinesisSink could not adjudicate a put_records response ({len(records)} "
                     f"record(s) sent, {len(results)} result(s) returned); abandoned, not retried",
                 )
-                return
+                return None
             records = verdict.retry
             if not records:
-                return
+                return sent
             if attempt >= self.max_retries:
                 self.failed += len(records)
                 _diag.lost(
@@ -115,4 +165,5 @@ class KinesisSink:
                     len(records),
                     f"KinesisSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
-                return
+                return sent - len(records)
+        return 0  # unreachable: the loop returns on every path (mypy needs the exit)

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/mongodb.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__ = ["MongoDBSink"]
 
@@ -46,13 +47,28 @@ class MongoDBSink:
             client = MongoClient(uri)
         self._client = client
         self._collection = client[database][collection]
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # having attempted no insert, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self.dropped_oversized = 0
         self._closed = False
 
+    def losses(self) -> SinkLosses:
+        """Oversized drops and documents the server rejected or never took (FR-002)."""
+        return SinkLosses(dropped=self.dropped_oversized, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Insert every event unordered; count bulk failures, retry connection errors (FR-003)."""
+        """Insert every event unordered; count bulk failures, retry connection errors (FR-003).
+
+        Raises when *nothing* was inserted (SPEC-026 FR-001) — a connection error past the retry
+        bound, or a bulk write every one of whose documents the server rejected. A bulk write
+        that stored some is partial and never raises: the unordered insert already committed
+        them, so the worker's retry would duplicate them.
+
+        A batch of nothing but oversized documents does not raise. They can never fit, so there
+        is nothing to retry; they are reported through ``losses().dropped``.
+        """
         documents = self._documents(batch)
         if not documents:
             return
@@ -67,9 +83,17 @@ class MongoDBSink:
                     # do not retry (successes are already in, a retry would duplicate/re-error).
                     rejects = len(details["writeErrors"])
                     self.failed += rejects
+                    total = rejects >= len(documents)
                     _diag.lost(
-                        "document", rejects, "MongoDBSink bulk write; the rest were inserted"
+                        "document",
+                        rejects,
+                        "MongoDBSink bulk write; none were inserted" if total
+                        else "MongoDBSink bulk write; the rest were inserted",
                     )
+                    if total:
+                        raise SinkDeliveryError(
+                            f"MongoDBSink inserted none of {len(documents)} document(s)"
+                        ) from None
                     return
                 if attempt < self.max_retries:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
@@ -80,7 +104,9 @@ class MongoDBSink:
                     len(documents),
                     f"MongoDBSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
-                return
+                raise SinkDeliveryError(
+                    f"MongoDBSink inserted none of {len(documents)} document(s)"
+                ) from None
 
     def close(self) -> None:
         """Close the client only if the sink owns it; idempotent (FR-005)."""

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/nats.py

@@ -14,6 +14,7 @@ import json
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["NATSSink"]
 
@@ -47,6 +48,10 @@ class NATSSink:
             return
         self._loop.run_until_complete(self._publish_all(batch))
 
+    def losses(self) -> SinkLosses:
+        """Events whose publish raised (SPEC-026 FR-002). Never raises."""
+        return SinkLosses(dropped=0, failed=self.failed)
+
     def close(self) -> None:
         """Drain/flush and close the connection, then close the managed loop (FR-007)."""
         if self._loop.is_closed():
@@ -59,13 +64,23 @@ class NATSSink:
     # -- internals ----------------------------------------------------------------------
 
     async def _publish_all(self, batch: list[dict[str, object]]) -> None:
+        """Publish each event, raising only when *none* of them landed (SPEC-026 FR-001).
+
+        Per-event isolation stays: a partial batch must not be retried wholesale, because the
+        events that published would be delivered twice.
+        """
         target = self._client.jetstream() if self._jetstream else self._client
+        published = 0
         for event in batch:
             try:
                 await target.publish(self._subject, json.dumps(event).encode("utf-8"))
-            except Exception as err:  # isolation boundary: never crash the worker (FR-011)
+            except Exception as err:  # isolation boundary: one event must not fail the batch
                 self.failed += 1
                 _diag.lost("event", 1, f"NATSSink publish, {type(err).__name__}")
+            else:
+                published += 1
+        if batch and not published:
+            raise SinkDeliveryError(f"NATSSink published none of {len(batch)} event(s)")
 
     async def _drain(self) -> None:
         drain = getattr(self._client, "drain", None)

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/postgres.py

@@ -15,6 +15,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__ = ["PostgresSink"]
 
@@ -39,7 +40,9 @@ class PostgresSink:
     ) -> 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
+        # having attempted no insert at all, and reported success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
         self._closed = False
         self._owns_connection = connection is None
@@ -54,8 +57,17 @@ class PostgresSink:
         if create_table:
             self._ensure_schema()
 
+    def losses(self) -> SinkLosses:
+        """Events 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 the whole batch in one transaction, rolling back and retrying on error (FR-004)."""
+        """Insert the whole batch in one transaction, rolling back and retrying on error (FR-004).
+
+        One transaction, rolled back on failure, so a batch past the retry bound inserted
+        *nothing*: it is counted and then raised (SPEC-026 FR-001). The rollback is what makes
+        the worker's retry safe here — there are no committed rows to duplicate.
+        """
         if not batch:
             return
         for attempt in range(self.max_retries + 1):
@@ -80,7 +92,9 @@ class PostgresSink:
                     len(batch),
                     f"PostgresSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
-                return
+                raise SinkDeliveryError(
+                    f"PostgresSink inserted none of {len(batch)} event(s)"
+                ) from None
 
     def close(self) -> None:
         """Commit pending work; close only an owned connection; idempotent (FR-005)."""

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/pubsub.py

@@ -12,6 +12,7 @@ import json
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["GooglePubSubSink"]
 
@@ -27,13 +28,41 @@ class GooglePubSubSink:
         self.topic = topic
         self.client = client
         self.failed = 0
+        self.rejected = 0
         self._futures: list[Any] = []
 
+    def losses(self) -> SinkLosses:
+        """Refused publishes and futures that resolved to an error (SPEC-026 FR-002).
+
+        ``failed`` only moves when the futures are resolved, which happens in :meth:`close` —
+        so a long-lived process reads zero here until it shuts down. That is a property of the
+        client's asynchronous publish, not of this accessor. Never raises.
+        """
+        return SinkLosses(dropped=self.rejected, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Publish one message per event, retaining each future for flush on close (FR-008)."""
+        """Publish one message per event, retaining each future for flush on close (FR-008).
+
+        ``publish()`` is a local hand-off returning a future, so a refusal here is the only
+        failure this call can observe; it is isolated per event and raises only when *every*
+        event was refused (SPEC-026 FR-001). Letting the first refusal propagate would hand the
+        worker a batch whose earlier events are already in flight, and the retry would duplicate
+        them.
+        """
+        published = 0
         for event in batch:
-            future = self.client.publish(self.topic, data=json.dumps(event).encode("utf-8"))
+            try:
+                future = self.client.publish(self.topic, data=json.dumps(event).encode("utf-8"))
+            except Exception as err:  # isolation boundary: one event must not fail the batch
+                self.rejected += 1
+                _diag.lost("event", 1, f"GooglePubSubSink publish, {type(err).__name__}")
+                continue
             self._futures.append(future)
+            published += 1
+        if batch and not published:
+            raise SinkDeliveryError(
+                f"GooglePubSubSink published none of {len(batch)} event(s)"
+            )
 
     def close(self) -> None:
         """Resolve all pending publish futures, counting/logging errors; idempotent (FR-008)."""

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/rabbitmq.py

@@ -13,6 +13,7 @@ import time
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["RabbitMQSink"]
 
@@ -45,17 +46,32 @@ class RabbitMQSink:
         self._exchange = exchange
         self._routing_key = routing_key
         self._url = url
-        self._max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value abandoned
+        # each message with no attempt made and no counter moved.
+        self._max_retries = max(max_retries, 0)
         self._owns_connection = connection is None
         self._connection = connection if connection is not None else self._connect()
         self._channel: Any = None
         self._properties: Any = None
         self.failed = 0
 
+    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 emit(self, batch: list[dict[str, object]]) -> None:
-        """Publish one persistent message per event, reconnecting on error (FR-006)."""
+        """Publish one persistent message per event, reconnecting on error (FR-006).
+
+        Raises when *no* message reached the broker (SPEC-026 FR-001) — a down broker is the
+        case the worker's retry and ``failed_batches`` exist for. A partial publish is counted
+        and left alone: retrying it would re-publish the messages already on the exchange.
+        """
+        published = 0
         for event in batch:
-            self._publish(json.dumps(event).encode("utf-8"))
+            if self._publish(json.dumps(event).encode("utf-8")):
+                published += 1
+        if batch and not published:
+            raise SinkDeliveryError(f"RabbitMQSink published none of {len(batch)} message(s)")
 
     def close(self) -> None:
         """Close the channel and (owned) connection; idempotent (FR-006)."""
@@ -68,7 +84,8 @@ class RabbitMQSink:
 
     # -- internals ----------------------------------------------------------------------
 
-    def _publish(self, body: bytes) -> None:
+    def _publish(self, body: bytes) -> bool:
+        """Publish one message within the retry bound; ``False`` once it is abandoned."""
         for attempt in range(self._max_retries + 1):
             try:
                 self._active_channel().basic_publish(
@@ -77,7 +94,7 @@ class RabbitMQSink:
                     body=body,
                     properties=self._persistent_properties(),
                 )
-                return
+                return True
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 self._reset()
                 if attempt < self._max_retries:
@@ -89,7 +106,8 @@ class RabbitMQSink:
                     1,
                     f"RabbitMQSink, {self._max_retries + 1} attempts, {type(err).__name__}",
                 )
-                return
+                return False
+        return False  # unreachable: the loop returns on every path (mypy needs the exit)
 
     def _active_channel(self) -> Any:
         if self._connection is None:

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/redis.py

@@ -15,6 +15,7 @@ import time
 from typing import Any
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["RedisListSink", "RedisStreamsSink"]
 
@@ -31,11 +32,22 @@ class _RedisSink:
 
             client = redis.Redis.from_url(url) if url else redis.Redis()
         self.client = client
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value made the
+        # retry range empty, so ``emit`` returned having attempted nothing — a silent success.
+        self.max_retries = max(max_retries, 0)
         self.failed = 0
 
+    def losses(self) -> SinkLosses:
+        """Events 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:
-        """Pipeline the whole batch into one round trip, retrying on connection error (FR-005)."""
+        """Pipeline the whole batch into one round trip, retrying on connection error (FR-005).
+
+        The batch travels as one pipeline, so a failure past the retry bound delivered *nothing*:
+        it is counted and then raised, giving the worker its retry and ``health()`` the loss
+        (SPEC-026 FR-001). There is no partial case to protect — the pipeline is all or nothing.
+        """
         if not batch:
             return
         for attempt in range(self.max_retries + 1):
@@ -55,7 +67,9 @@ class _RedisSink:
                     len(batch),
                     f"{type(self).__name__}, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
-                return
+                raise SinkDeliveryError(
+                    f"{type(self).__name__} delivered none of {len(batch)} event(s)"
+                ) from None
 
     def close(self) -> None:
         """Close the connection only if the sink owns it (FR-005)."""

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/sns.py

@@ -12,6 +12,7 @@ from typing import Any
 
 from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_items
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["SNSSink"]
 
@@ -29,17 +30,33 @@ class SNSSink:
             client = boto3.client("sns")
         self.topic_arn = topic_arn
         self.client = client
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_send`` having published 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 entries still failing past the retry bound (FR-002)."""
+        return SinkLosses(dropped=self.dropped_oversized, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Re-chunk to publish_batch limits and send each chunk, retrying failures (FR-010)."""
+        """Re-chunk to publish_batch limits and send each chunk, retrying failures (FR-010).
+
+        Raises when every chunk failed and at least one was sent (SPEC-026 FR-001). Events
+        dropped before sending — too large to ever fit — are not a send failure and do not
+        make a batch of nothing but oversized events raise; they can never be retried into
+        existence, and are reported through ``losses().dropped``.
+        """
         bodies = self._bodies(batch)
+        chunks = delivered = 0
         for chunk in chunk_items(
             bodies, max_count=self.MAX_BATCH, max_bytes=self.MAX_BYTES, size_of=len
         ):
-            self._send(chunk)
+            chunks += 1
+            delivered += self._send(chunk)
+        if chunks and not delivered:
+            raise SinkDeliveryError(f"SNSSink published none of {chunks} chunk(s)")
 
     def close(self) -> None:
         """No-op: the sink buffers nothing internally (FR-001)."""
@@ -58,8 +75,13 @@ class SNSSink:
             bodies.append(body)
         return bodies
 
-    def _send(self, bodies: list[str]) -> None:
-        """Publish one chunk, retrying only the ``Failed`` entries (bounded) (FR-010)."""
+    def _send(self, bodies: list[str]) -> int:
+        """Publish one chunk, retrying only the ``Failed`` entries (bounded) (FR-010).
+
+        Returns how many entries SNS accepted, so ``emit`` can tell "nothing landed" from a
+        partial success. A chunk whose entries all failed contributes ``0``.
+        """
+        sent = len(bodies)
         entries = [{"Id": str(i), "Message": body} for i, body in enumerate(bodies)]
         for attempt in range(self.max_retries + 1):
             response = self.client.publish_batch(
@@ -67,7 +89,7 @@ class SNSSink:
             )
             failed = response.get("Failed", [])
             if not failed:
-                return
+                return sent
             failed_ids = {entry["Id"] for entry in failed}
             entries = [entry for entry in entries if entry["Id"] in failed_ids]
             if attempt >= self.max_retries:
@@ -77,4 +99,5 @@ class SNSSink:
                     len(entries),
                     f"SNSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
-                return
+                return sent - len(entries)
+        return 0  # unreachable: the loop returns on every path (mypy needs the exit)

{log_foundry-0.10.2.dev17 → log_foundry-0.10.2.dev18}/src/log_foundry/sinks/sqs.py

@@ -35,6 +35,7 @@ from collections.abc import Callable
 from typing import Any, NamedTuple
 
 from log_foundry import _diag
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["SQSSink"]
 
@@ -95,7 +96,9 @@ class SQSSink:
             client = boto3.client("sqs")
         self.queue_url = queue_url
         self.client = client
-        self.max_retries = max_retries
+        # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
+        # from ``_send`` having sent nothing, and reported success.
+        self.max_retries = max(max_retries, 0)
         # AWS requires every FIFO queue name to end in '.fifo', so the suffix is a contract
         # rather than a guess — but an explicit flag still wins. Decided once, not per emit.
         self.fifo = queue_url.endswith(".fifo") if fifo is None else fifo
@@ -104,10 +107,45 @@ class SQSSink:
         self.dropped_oversized = 0  # events too large to ever fit one message
         self.failed = 0  # entries still failing after the retry bound
 
+    def losses(self) -> SinkLosses:
+        """Oversized drops and entries still failing past the retry bound (FR-002).
+
+        Sender faults land in ``failed`` alongside the retry-exhausted entries: SQS rejected the
+        request itself, so the entry is as lost as one that timed out, and SPEC-016 settled that
+        it must not be re-sent byte-identical. Never raises.
+        """
+        return SinkLosses(dropped=self.dropped_oversized, failed=self.failed)
+
     def emit(self, batch: list[dict[str, object]]) -> None:
-        """Re-chunk ``batch`` to SQS limits and send each chunk (FR-001, FR-002)."""
+        """Re-chunk ``batch`` to SQS limits and send each chunk (FR-001, FR-002).
+
+        Raises when every chunk failed and at least one was sent (SPEC-026 FR-001). An event
+        dropped for exceeding the message limit is not a send failure — it can never fit — so a
+        batch of nothing but oversized events produces no chunks and does not raise; it is
+        reported through ``losses().dropped``.
+
+        Nor does a batch whose chunks SQS rejected *entirely* as sender faults. Those entries
+        are lost, but re-sending them byte-identical can only fail the same way, and SPEC-016
+        FR-006 settled that they are abandoned rather than retried — so making the worker retry
+        them would undo that decision one level up. They are reported through ``losses().failed``.
+
+        That suppression is conditional, not batch-wide. If any chunk was lost for a *retryable*
+        reason — a throttle, an internal error, still failing at the bound — the raise stands,
+        because those events are recoverable and nothing landed for the retry to duplicate. The
+        cost is that the sender-fault chunk is re-sent and re-rejected alongside them, which is
+        futile but harmless; silently dropping recoverable events to avoid it would be the
+        failure SPEC-026 exists to remove. A batch of nothing *but* sender faults still keeps
+        FR-006 exactly.
+        """
+        chunks = delivered = 0
+        recoverable_loss = False
         for chunk in self._chunks(batch):
-            self._send(chunk)
+            chunks += 1
+            accepted, retryable_lost = self._send(chunk)
+            delivered += accepted
+            recoverable_loss = recoverable_loss or retryable_lost
+        if chunks and not delivered and recoverable_loss:
+            raise SinkDeliveryError(f"SQSSink delivered none of {chunks} chunk(s)")
 
     def close(self) -> None:
         """No-op: the sink buffers nothing internally (FR-005)."""
@@ -192,9 +230,15 @@ class SQSSink:
             chunks.append(current)
         return chunks
 
-    def _send(self, prepared: list[_Prepared]) -> None:
+    def _send(self, prepared: list[_Prepared]) -> tuple[int, bool]:
         """Send one valid chunk, retrying only the ``Failed`` entries with a bounded count.
 
+        Returns ``(accepted, retryable_lost)``. ``accepted`` lets ``emit`` tell "nothing landed"
+        from a partial success (SPEC-026 FR-001); ``retryable_lost`` says whether anything was
+        given up on that a re-send could plausibly recover. A chunk SQS rejected wholesale as
+        invalid reports ``False`` there, because re-sending those entries byte-identical can
+        only fail the same way (SPEC-016 FR-006).
+
         Successfully-sent entries are never re-sent; entries still failing past ``max_retries``
         are counted (``failed``) and logged, not silently dropped (FR-003). The FIFO parameters
         are attached only when the queue is FIFO, so a standard queue's entries are exactly
@@ -213,11 +257,21 @@ class SQSSink:
             if item.dedup_id is not None:
                 entry["MessageDeduplicationId"] = item.dedup_id
             entries.append(entry)
+        accepted = 0
         for attempt in range(self.max_retries + 1):
             response = self.client.send_message_batch(QueueUrl=self.queue_url, Entries=entries)
             failed = response.get("Failed", [])
+            # Accumulated per attempt, not derived at the end: after the first response
+            # ``entries`` is already narrowed to the failures, so each round's difference is
+            # what that round put on the queue.
+            # Matched by ``Id`` rather than counted: a ``Failed`` array carrying a duplicate or
+            # an unknown id would otherwise understate ``accepted`` — possibly below zero — and
+            # turn a partial success into a false "nothing landed". Unreachable from real SQS,
+            # guarded anyway because the cost is one set intersection.
+            failed_ids = {item.get("Id") for item in failed}
+            accepted += sum(1 for entry in entries if entry["Id"] not in failed_ids)
             if not failed:
-                return
+                return accepted, False
             # Abandon sender faults immediately and name the code: the retry would re-send the
             # entry byte-identical, and the code is the only thing that makes a rejection
             # diagnosable from the log line alone. A missing flag is treated as retryable, so
@@ -237,7 +291,10 @@ class SQSSink:
 
             retryable_ids = {item["Id"] for item in failed if not item.get("SenderFault")}
             if not retryable_ids:
-                return
+                # Everything left is a sender fault: counted, and not worth re-sending
+                # (SPEC-016 FR-006). ``False`` keeps this chunk alone from making ``emit``
+                # report a total failure the worker would answer with that re-send.
+                return accepted, False
             entries = [entry for entry in entries if entry["Id"] in retryable_ids]
             if attempt >= self.max_retries:
                 self.failed += len(entries)
@@ -246,4 +303,5 @@ class SQSSink:
                     len(entries),
                     f"SQSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
-                return
+                return accepted, True
+        return accepted, False  # unreachable: the loop returns on every path