log-foundry 0.10.2.dev13__tar.gz → 0.10.2.dev14__tar.gz

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/PKG-INFO

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

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/pyproject.toml

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

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/_socket.py

@@ -12,9 +12,10 @@ substitute a fake socket without any network access.
 from __future__ import annotations
 
 import socket
-import sys
 import time
 
+from log_foundry import _diag
+
 __all__ = ["SocketTransport"]
 
 _BACKOFF_BASE = 0.1  # seconds; delay for retry attempt n is _BACKOFF_BASE * 2**n
@@ -81,9 +82,15 @@ class SocketTransport:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: SocketTransport abandoned a message after "
-                    f"{self._max_retries + 1} attempt(s) ({err!r})\n"
+                # Guarded now (SPEC-029 FR-003): this runs on the worker thread, and the bare
+                # ``sys.stderr.write`` this replaced could end delivery for good. ``errno``
+                # because an ``OSError`` type name alone does not tell "connection refused" from
+                # "host unknown", and the code is an integer from the OS — not caller data.
+                _diag.lost(
+                    "message",
+                    1,
+                    f"SocketTransport, {self._max_retries + 1} attempt(s), "
+                    f"{type(err).__name__} {_diag.errno_of(err)}".rstrip(),
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/clickhouse.py

@@ -9,10 +9,10 @@ idempotent ``MergeTree`` ``create_table`` convenience is off by default. Write-o
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
 
 __all__ = ["ClickHouseSink"]
@@ -97,9 +97,10 @@ class ClickHouseSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(rows)
-                sys.stderr.write(
-                    f"log-foundry: ClickHouseSink abandoned {len(rows)} row(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "row",
+                    len(rows),
+                    f"ClickHouseSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/elasticsearch.py

@@ -10,8 +10,8 @@ without discarding the successfully-indexed items. OpenSearch speaks the same bu
 from __future__ import annotations
 
 import json
-import sys
 
+from log_foundry import _diag
 from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["ElasticsearchSink", "OpenSearchSink"]
@@ -61,7 +61,7 @@ class ElasticsearchSink(HTTPSink):
                 errors += 1
         if errors:
             self.item_errors += errors
-            sys.stderr.write(f"log-foundry: ElasticsearchSink saw {errors} failed bulk item(s)\n")
+            _diag.lost("bulk item", errors, f"{type(self).__name__}, rejected by the server")
 
 
 class OpenSearchSink(ElasticsearchSink):

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/eventhubs.py

@@ -10,10 +10,11 @@ send errors are retried within a bound. ``close()`` closes the producer.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["AzureEventHubsSink"]
 
 _BACKOFF_BASE = 0.1
@@ -62,10 +63,7 @@ class AzureEventHubsSink:
             current = self.producer.create_batch()
             if not _try_add(current, data):
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    "log-foundry: AzureEventHubsSink dropped an event too large for an "
-                    "empty 1 MB batch\n"
-                )
+                _diag.lost("event", 1, "AzureEventHubsSink, too large for an empty 1 MB batch")
         self._send(current)
 
     def close(self) -> None:
@@ -87,9 +85,11 @@ class AzureEventHubsSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(event_batch)
-                sys.stderr.write(
-                    f"log-foundry: AzureEventHubsSink abandoned a batch of {len(event_batch)} "
-                    f"event(s) after {self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "event",
+                    len(event_batch),
+                    f"AzureEventHubsSink, one batch, {self.max_retries + 1} attempts, "
+                    f"{type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/firehose.py

@@ -9,9 +9,9 @@ retried within a bounded count.
 from __future__ import annotations
 
 import json
-import sys
 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
 
@@ -69,9 +69,11 @@ class FirehoseSink:
             data = json.dumps(event).encode("utf-8")
             if len(data) > self.MAX_RECORD_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: FirehoseSink dropped an event of {len(data)} bytes exceeding "
-                    f"the {self.MAX_RECORD_BYTES}-byte per-record limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"FirehoseSink, {len(data)} bytes exceeds the "
+                    f"{self.MAX_RECORD_BYTES}-byte per-record limit",
                 )
                 continue
             records.append({"Data": data})
@@ -89,10 +91,12 @@ class FirehoseSink:
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
                 self.dropped_unadjudicated += verdict.unadjudicated
-                sys.stderr.write(
-                    f"log-foundry: FirehoseSink could not adjudicate a put_record_batch response "
+                _diag.lost(
+                    "record",
+                    verdict.unadjudicated,
+                    f"FirehoseSink could not adjudicate a put_record_batch response "
                     f"({len(records)} record(s) sent, {len(results)} result(s) returned); "
-                    f"{verdict.unadjudicated} record(s) abandoned\n"
+                    f"abandoned, not retried",
                 )
                 return
             records = verdict.retry
@@ -100,8 +104,9 @@ class FirehoseSink:
                 return
             if attempt >= self.max_retries:
                 self.failed += len(records)
-                sys.stderr.write(
-                    f"log-foundry: {len(records)} Firehose record(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"FirehoseSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/http.py

@@ -15,13 +15,14 @@ from __future__ import annotations
 
 import gzip as _gzip
 import json
-import sys
 import time
 import urllib.error
 import urllib.request
 from base64 import b64encode
 from typing import TYPE_CHECKING, Any
 
+from log_foundry import _diag
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
@@ -128,7 +129,11 @@ class HTTPSink:
                 if attempt < self.max_retries:
                     self._sleep_backoff(attempt, None)
                     continue
-                self._abandon(f"connection error: {err!r}")
+                # The type plus the OS code, never the message: a ``URLError``'s text embeds the
+                # URL and whatever the resolver said (SPEC-029 FR-002).
+                self._abandon(
+                    f"connection error, {type(err).__name__} {_diag.errno_of(err)}".rstrip()
+                )
                 return None
             if 200 <= status < 300:
                 return payload
@@ -198,11 +203,14 @@ class HTTPSink:
         time.sleep(delay)
 
     def _abandon(self, reason: str) -> None:
-        """Count and log a request abandoned past the retry bound (FR-012)."""
+        """Count and log 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).
+        """
         self.failed += 1
-        sys.stderr.write(
-            f"log-foundry: {type(self).__name__} abandoned a request after "
-            f"{self.max_retries + 1} attempt(s) ({reason})\n"
+        _diag.lost(
+            "request", 1, f"{type(self).__name__}, {self.max_retries + 1} attempt(s), {reason}"
         )
 
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/kafka.py

@@ -10,9 +10,10 @@ raised out of ``emit``.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["KafkaSink"]
 
 
@@ -65,7 +66,34 @@ class KafkaSink:
         return str(value).encode("utf-8") if value is not None else None
 
     def _on_delivery(self, err: object, msg: object) -> None:
-        """confluent-kafka delivery callback: count and log failures (FR-002)."""
+        """confluent-kafka delivery callback: count and log failures (FR-002).
+
+        ``err`` is a ``KafkaError``, not an exception, so it goes to :func:`~_diag.lost` rather
+        than :func:`~_diag.absorbed`. Its ``str`` is a human message that can quote the record, so
+        only the type and the numeric ``code()`` are written — the code is librdkafka's own
+        enumeration and is what makes a delivery failure diagnosable (SPEC-029 FR-002).
+        """
         if err is not None:
             self.failed += 1
-            sys.stderr.write(f"log-foundry: KafkaSink delivery failed: {err!r}\n")
+            _diag.lost("message", 1, f"KafkaSink delivery, {type(err).__name__}{_code(err)}")
+
+
+def _code(err: object) -> str:
+    """Render a ``KafkaError``'s numeric code as ``" code=N"``, or ``""`` if it has none.
+
+    ``code()`` is a method on confluent-kafka's ``KafkaError``, returns one of librdkafka's
+    integer constants, and carries no caller data. Deliberately narrow: only an ``int`` is written,
+    so a stub or a future version returning something else contributes nothing rather than
+    smuggling text past the type-name rule.
+
+    Total, and the ``int()`` is inside the guard for the same reason ``_diag.errno_of`` puts it
+    there: ``isinstance(code, int)`` admits a *subclass*, whose ``__int__`` is Python that can
+    raise — and this runs in a delivery callback, so an escaping exception would surface from
+    ``emit`` and cost the whole batch. A diagnostic can never be the failure (SPEC-029 FR-003).
+    """
+    try:
+        code = getattr(err, "code", None)
+        value = code() if callable(code) else None
+        return f" code={int(value)}" if isinstance(value, int) else ""
+    except Exception:
+        return ""

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/kinesis.py

@@ -10,9 +10,9 @@ unless a sink is built without an injected client. Each incoming batch is re-chu
 from __future__ import annotations
 
 import json
-import sys
 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
 
@@ -77,9 +77,11 @@ class KinesisSink:
             data = json.dumps(event).encode("utf-8")
             if len(data) > self.MAX_RECORD_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: KinesisSink dropped an event of {len(data)} bytes exceeding "
-                    f"the {self.MAX_RECORD_BYTES}-byte per-record limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"KinesisSink, {len(data)} bytes exceeds the "
+                    f"{self.MAX_RECORD_BYTES}-byte per-record limit",
                 )
                 continue
             key = str(event.get(self.partition_key_field) or "log-foundry")[:256]
@@ -96,10 +98,11 @@ class KinesisSink:
             verdict = adjudicate_positional(records, results)
             if verdict.unadjudicated:
                 self.dropped_unadjudicated += verdict.unadjudicated
-                sys.stderr.write(
-                    f"log-foundry: KinesisSink could not adjudicate a put_records response "
-                    f"({len(records)} record(s) sent, {len(results)} result(s) returned); "
-                    f"{verdict.unadjudicated} record(s) abandoned\n"
+                _diag.lost(
+                    "record",
+                    verdict.unadjudicated,
+                    f"KinesisSink could not adjudicate a put_records response ({len(records)} "
+                    f"record(s) sent, {len(results)} result(s) returned); abandoned, not retried",
                 )
                 return
             records = verdict.retry
@@ -107,8 +110,9 @@ class KinesisSink:
                 return
             if attempt >= self.max_retries:
                 self.failed += len(records)
-                sys.stderr.write(
-                    f"log-foundry: {len(records)} Kinesis record(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"KinesisSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/mongodb.py

@@ -10,10 +10,11 @@ documents retained. Write-only — querying is the downstream tool's job.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["MongoDBSink"]
 
 _BACKOFF_BASE = 0.1
@@ -66,18 +67,18 @@ class MongoDBSink:
                     # do not retry (successes are already in, a retry would duplicate/re-error).
                     rejects = len(details["writeErrors"])
                     self.failed += rejects
-                    sys.stderr.write(
-                        f"log-foundry: MongoDBSink had {rejects} document(s) rejected by a bulk "
-                        f"write; the rest were inserted\n"
+                    _diag.lost(
+                        "document", rejects, "MongoDBSink bulk write; the rest were inserted"
                     )
                     return
                 if attempt < self.max_retries:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(documents)
-                sys.stderr.write(
-                    f"log-foundry: MongoDBSink abandoned {len(documents)} document(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "document",
+                    len(documents),
+                    f"MongoDBSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 
@@ -97,9 +98,7 @@ class MongoDBSink:
         for event in batch:
             if len(json.dumps(event).encode("utf-8")) > _MAX_DOC_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    "log-foundry: MongoDBSink dropped a document exceeding the 16 MB limit\n"
-                )
+                _diag.lost("document", 1, "MongoDBSink, exceeds the 16 MB limit")
                 continue
             documents.append(dict(event))
         return documents

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/multi.py

@@ -16,9 +16,10 @@ has nothing to retry.
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING
 
+from log_foundry import _diag
+
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
 
@@ -58,9 +59,10 @@ class MultiSink:
                 self.failed += 1
                 if first_error is None:
                     first_error = err
-                sys.stderr.write(
-                    f"log-foundry: MultiSink child {type(sink).__name__}.emit "
-                    f"failed and was skipped: {err!r}\n"
+                # The class name goes in the *detail*, not in ``where``: only the detail is
+                # bounded, and a child's ``__name__`` is a runtime value (SPEC-029 FR-002).
+                _diag.absorbed(
+                    "emitting to a MultiSink child", err, f"{type(sink).__name__} skipped"
                 )
             else:
                 delivered += 1
@@ -78,7 +80,4 @@ class MultiSink:
                 sink.close()
             except Exception as err:  # close-all: an earlier failure must not skip the rest
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: MultiSink child {type(sink).__name__}.close "
-                    f"failed and was skipped: {err!r}\n"
-                )
+                _diag.absorbed("closing a MultiSink child", err, f"{type(sink).__name__} skipped")

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/nats.py

@@ -11,9 +11,10 @@ from __future__ import annotations
 
 import asyncio
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["NATSSink"]
 
 
@@ -64,7 +65,7 @@ class NATSSink:
                 await target.publish(self._subject, json.dumps(event).encode("utf-8"))
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 self.failed += 1
-                sys.stderr.write(f"log-foundry: NATSSink publish failed: {err!r}\n")
+                _diag.lost("event", 1, f"NATSSink publish, {type(err).__name__}")
 
     async def _drain(self) -> None:
         drain = getattr(self._client, "drain", None)

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/postgres.py

@@ -10,10 +10,10 @@ convenience is off by default — the user owns their schema and indexes.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
 
 __all__ = ["PostgresSink"]
@@ -71,9 +71,14 @@ class PostgresSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(batch)
-                sys.stderr.write(
-                    f"log-foundry: PostgresSink abandoned {len(batch)} event(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                # The type, never the repr. ``_row`` binds the whole ``json.dumps(event)`` as a
+                # statement parameter, and a psycopg error repr routinely reprints the failing
+                # statement *and* its parameters — so the old line reprinted the event, PII
+                # included, into a stream nobody was asked to secure (SPEC-029 FR-002, arch §6).
+                _diag.lost(
+                    "event",
+                    len(batch),
+                    f"PostgresSink, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/pubsub.py

@@ -9,9 +9,10 @@ are counted and logged.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["GooglePubSubSink"]
 
 
@@ -41,5 +42,5 @@ class GooglePubSubSink:
                 future.result()
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 self.failed += 1
-                sys.stderr.write(f"log-foundry: GooglePubSubSink publish failed: {err!r}\n")
+                _diag.lost("event", 1, f"GooglePubSubSink publish, {type(err).__name__}")
         self._futures.clear()

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/rabbitmq.py

@@ -9,10 +9,11 @@ and counted; ``close()`` closes the channel and connection.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["RabbitMQSink"]
 
 _BACKOFF_BASE = 0.1
@@ -83,9 +84,10 @@ class RabbitMQSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += 1
-                sys.stderr.write(
-                    f"log-foundry: RabbitMQSink abandoned a message after "
-                    f"{self._max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "message",
+                    1,
+                    f"RabbitMQSink, {self._max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/redis.py

@@ -11,10 +11,11 @@ shadows or requires the real ``redis`` package at import time.
 from __future__ import annotations
 
 import json
-import sys
 import time
 from typing import Any
 
+from log_foundry import _diag
+
 __all__ = ["RedisListSink", "RedisStreamsSink"]
 
 _BACKOFF_BASE = 0.1
@@ -49,9 +50,10 @@ class _RedisSink:
                     time.sleep(_BACKOFF_BASE * (2**attempt))
                     continue
                 self.failed += len(batch)
-                sys.stderr.write(
-                    f"log-foundry: {type(self).__name__} abandoned {len(batch)} event(s) after "
-                    f"{self.max_retries + 1} attempts ({err!r})\n"
+                _diag.lost(
+                    "event",
+                    len(batch),
+                    f"{type(self).__name__}, {self.max_retries + 1} attempts, {type(err).__name__}",
                 )
                 return
 

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/sns.py

@@ -8,9 +8,9 @@ request, ≤ 256 KB total). ``boto3`` is the optional ``aws`` extra, imported la
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any
 
+from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_items
 
 __all__ = ["SNSSink"]
@@ -53,10 +53,7 @@ class SNSSink:
             body = json.dumps(event)
             if len(body.encode("utf-8")) > self.MAX_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: SNSSink dropped an event exceeding the "
-                    f"{self.MAX_BYTES}-byte message limit\n"
-                )
+                _diag.lost("event", 1, f"SNSSink, exceeds the {self.MAX_BYTES}-byte message limit")
                 continue
             bodies.append(body)
         return bodies
@@ -75,8 +72,9 @@ class SNSSink:
             entries = [entry for entry in entries if entry["Id"] in failed_ids]
             if attempt >= self.max_retries:
                 self.failed += len(entries)
-                sys.stderr.write(
-                    f"log-foundry: {len(entries)} SNS message(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SNSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return

{log_foundry-0.10.2.dev13 → log_foundry-0.10.2.dev14}/src/log_foundry/sinks/sqs.py

@@ -31,10 +31,11 @@ is not done.
 from __future__ import annotations
 
 import json
-import sys
 from collections.abc import Callable
 from typing import Any, NamedTuple
 
+from log_foundry import _diag
+
 __all__ = ["SQSSink"]
 
 DEFAULT_GROUP_ID = "log-foundry"
@@ -173,9 +174,10 @@ class SQSSink:
                 size += len(group_id.encode("utf-8")) + len(dedup_id.encode("utf-8"))
             if size > self.MAX_BYTES:
                 self.dropped_oversized += 1
-                sys.stderr.write(
-                    f"log-foundry: dropped an event of {size} bytes exceeding the "
-                    f"{self.MAX_BYTES}-byte SQS message limit\n"
+                _diag.lost(
+                    "event",
+                    1,
+                    f"SQSSink, {size} bytes exceeds the {self.MAX_BYTES}-byte message limit",
                 )
                 continue
             if current and (
@@ -223,9 +225,14 @@ class SQSSink:
             sender_faults = [item for item in failed if item.get("SenderFault")]
             if sender_faults:
                 self.failed += len(sender_faults)
-                sys.stderr.write(
-                    f"log-foundry: {len(sender_faults)} SQS message(s) rejected as invalid "
-                    f"(first code: {sender_faults[0].get('Code', 'unknown')}); not retried\n"
+                # The AWS error code is library-controlled in the sense that matters — it is an
+                # enumerated API constant, not the event — and ``_diag`` bounds and escapes it
+                # regardless, so a surprising response shape cannot forge a line (SPEC-029).
+                _diag.lost(
+                    "message",
+                    len(sender_faults),
+                    f"SQSSink, rejected as invalid (first code: "
+                    f"{sender_faults[0].get('Code', 'unknown')}); not retried",
                 )
 
             retryable_ids = {item["Id"] for item in failed if not item.get("SenderFault")}
@@ -234,8 +241,9 @@ class SQSSink:
             entries = [entry for entry in entries if entry["Id"] in retryable_ids]
             if attempt >= self.max_retries:
                 self.failed += len(entries)
-                sys.stderr.write(
-                    f"log-foundry: {len(entries)} SQS message(s) still failing after "
-                    f"{self.max_retries + 1} attempts; abandoned\n"
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SQSSink, still failing after {self.max_retries + 1} attempts; abandoned",
                 )
                 return