log-foundry 0.10.2.dev72__tar.gz → 0.10.2.dev74__tar.gz

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev72
+Version: 0.10.2.dev74
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -694,7 +694,7 @@ completed, not that every chunk of it landed.
 | `ElasticsearchSink` | `log_foundry.sinks.elasticsearch` | `ElasticsearchSink(url, *, index, auth=None, **http_kwargs)` — POST to `_bulk`, parsing per-item errors (`.item_errors`) |
 | `OpenSearchSink` | `log_foundry.sinks.elasticsearch` | same signature as `ElasticsearchSink` (identical bulk protocol) |
 | `LokiSink` | `log_foundry.sinks.loki` | `LokiSink(url, *, labels=("service", "env", "level"), **http_kwargs)` — Grafana Loki push API |
-| `LogstashSink` | `log_foundry.sinks.logstash` | `LogstashSink(url=…, **http_kwargs)` for HTTP, **or** `LogstashSink(host=…, port=…, transport="tcp")` for a raw TCP/UDP socket |
+| `LogstashSink` | `log_foundry.sinks.logstash` | `LogstashSink(url=…, body_format="json_array", **http_kwargs)` for HTTP, **or** `LogstashSink(host=…, port=…, transport="tcp")` for a raw TCP/UDP socket. HTTP mode posts a JSON array as `application/json`, which a **stock** `http` input parses into one event per element; pass `body_format="ndjson"` for an input configured with `additional_codecs => {"application/x-ndjson" => "json_lines"}`, which that setting *replaces* the default map to provide |
 | `SyslogSink` | `log_foundry.sinks.syslog` | `SyslogSink(host, port=514, *, transport="udp", facility="user", app_name="log-foundry", max_datagram_bytes=65507)` — RFC 5424 over UDP/TCP. A UDP frame over the limit is dropped and counted rather than sent, retried and abandoned; TCP is a stream and is unaffected |
 
 ```python
@@ -706,7 +706,7 @@ lf.configure(sink=ElasticsearchSink("https://es.internal:9200", index="app-logs"
 #### SaaS platforms
 
 Also HTTP-based. All are zero-dependency **except** `SentrySink`, which prefers the `sentry-sdk`
-(the `sentry` extra) and falls back to raw HTTP envelopes when it isn't installed.
+(the `sentry` extra) and falls back to raw HTTP envelopes when it cannot deliver through one.
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
@@ -714,11 +714,28 @@ Also HTTP-based. All are zero-dependency **except** `SentrySink`, which prefers
 | `SplunkHECSink` | `log_foundry.sinks.splunk` | — | `SplunkHECSink(url, token, *, host=None, source="log-foundry")` — HTTP Event Collector |
 | `NewRelicSink` | `log_foundry.sinks.newrelic` | — | `NewRelicSink(api_key, *, region="US")` — `region` is `"US"` or `"EU"` |
 | `HoneycombSink` | `log_foundry.sinks.honeycomb` | — | `HoneycombSink(api_key, dataset, *, url="https://api.honeycomb.io")` |
-| `SentrySink` | `log_foundry.sinks.sentry` | `sentry` | `SentrySink(dsn=None, *, min_level="ERROR")` — sends only `min_level`+ events |
+| `SentrySink` | `log_foundry.sinks.sentry` | `sentry` | `SentrySink(dsn=None, *, min_level="ERROR", backend="auto")` — sends only `min_level`+ events |
 
-With the `sentry` extra installed, `SentrySink` captures via `sentry_sdk.capture_event` (initialize
-the SDK yourself with `sentry_sdk.init(...)`); without it, pass `dsn=` and events are POSTed as
-Sentry envelopes over HTTP.
+`SentrySink` captures via `sentry_sdk.capture_event` when the SDK can deliver — you initialize it
+yourself with `sentry_sdk.init(...)` — and POSTs Sentry envelopes over HTTP to `dsn=` otherwise.
+With neither a deliverable SDK nor a `dsn=`, a batch is **refused** rather than silently dropped.
+`backend=` decides:
+
+| `backend=` | What it uses |
+|---|---|
+| `"auto"` (default) | the SDK when it can deliver, otherwise the HTTP fallback; re-decided on every batch, so an `init(...)` that arrives after the sink was built is picked up |
+| `"sdk"` | the SDK only. A client that cannot deliver **refuses the batch** rather than quietly switching transport |
+| `"http"` | the HTTP fallback only. No SDK is held, consulted or flushed |
+
+"Can deliver" means the SDK's client reports itself active *and* holds a transport. An
+uninitialized process, an `init()` with no DSN, and a `close()`d client all fail that — the first
+reports itself inactive, the other two report themselves active with nothing to send through, and
+all three drop events silently.
+
+An argument the chosen backend can never use is a `ValueError` rather than a silent ignore:
+`opener=` where no HTTP fallback is built, `client=` under `backend="http"`. Until this release
+`opener=` was accepted and then ignored whenever the SDK happened to import — including when it was
+installed as somebody else's transitive dependency.
 
 #### AWS — the durable-buffer path (`aws` extra)
 
@@ -797,7 +814,16 @@ Two things worth knowing:
 
 #### Queue & stream
 
-Each needs its own extra (lazy-imported). All publish + retry within a bound and close cleanly.
+Each needs its own extra (lazy-imported). All publish within a bound and close cleanly. **Where the
+retry lives differs, and it was measured rather than assumed** (SPEC-041 FR-004): the Redis,
+RabbitMQ and Event Hubs sinks retry through `sinks/_retry`, so their backoff is bounded *and* cut
+short by a shutdown. `KafkaSink`, `NATSSink` and `GooglePubSubSink` add no retry loop and need
+none — each hands off locally and returns without waiting, so nothing of theirs holds the single
+drain thread. Their clients retry on their own threads within their own bounds:
+`message.timeout.ms` (5 min default) for Kafka, a 600 s deadline for Pub/Sub, and for NATS a
+JetStream publish bounded by its 5 s ack timeout with no retry at all. `NATSSink` refuses a batch
+outright while its client reports itself disconnected, so a sustained outage moves
+`health().failed_batches` instead of being absorbed.
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
@@ -821,7 +847,7 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
 | `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…")` |
-| `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False)` — JSONB `event` column + extracted columns |
+| `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False, connect_timeout=5)` — JSONB `event` column + extracted columns. Reconnects an **owned** connection the server has closed; a `connection=` you inject is never reopened. `connect_timeout` is passed to libpq explicitly, so it **overrides** any `connect_timeout` in your DSN |
 | `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False)` — MergeTree, columnar insert |
 
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/README.md

@@ -658,7 +658,7 @@ completed, not that every chunk of it landed.
 | `ElasticsearchSink` | `log_foundry.sinks.elasticsearch` | `ElasticsearchSink(url, *, index, auth=None, **http_kwargs)` — POST to `_bulk`, parsing per-item errors (`.item_errors`) |
 | `OpenSearchSink` | `log_foundry.sinks.elasticsearch` | same signature as `ElasticsearchSink` (identical bulk protocol) |
 | `LokiSink` | `log_foundry.sinks.loki` | `LokiSink(url, *, labels=("service", "env", "level"), **http_kwargs)` — Grafana Loki push API |
-| `LogstashSink` | `log_foundry.sinks.logstash` | `LogstashSink(url=…, **http_kwargs)` for HTTP, **or** `LogstashSink(host=…, port=…, transport="tcp")` for a raw TCP/UDP socket |
+| `LogstashSink` | `log_foundry.sinks.logstash` | `LogstashSink(url=…, body_format="json_array", **http_kwargs)` for HTTP, **or** `LogstashSink(host=…, port=…, transport="tcp")` for a raw TCP/UDP socket. HTTP mode posts a JSON array as `application/json`, which a **stock** `http` input parses into one event per element; pass `body_format="ndjson"` for an input configured with `additional_codecs => {"application/x-ndjson" => "json_lines"}`, which that setting *replaces* the default map to provide |
 | `SyslogSink` | `log_foundry.sinks.syslog` | `SyslogSink(host, port=514, *, transport="udp", facility="user", app_name="log-foundry", max_datagram_bytes=65507)` — RFC 5424 over UDP/TCP. A UDP frame over the limit is dropped and counted rather than sent, retried and abandoned; TCP is a stream and is unaffected |
 
 ```python
@@ -670,7 +670,7 @@ lf.configure(sink=ElasticsearchSink("https://es.internal:9200", index="app-logs"
 #### SaaS platforms
 
 Also HTTP-based. All are zero-dependency **except** `SentrySink`, which prefers the `sentry-sdk`
-(the `sentry` extra) and falls back to raw HTTP envelopes when it isn't installed.
+(the `sentry` extra) and falls back to raw HTTP envelopes when it cannot deliver through one.
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
@@ -678,11 +678,28 @@ Also HTTP-based. All are zero-dependency **except** `SentrySink`, which prefers
 | `SplunkHECSink` | `log_foundry.sinks.splunk` | — | `SplunkHECSink(url, token, *, host=None, source="log-foundry")` — HTTP Event Collector |
 | `NewRelicSink` | `log_foundry.sinks.newrelic` | — | `NewRelicSink(api_key, *, region="US")` — `region` is `"US"` or `"EU"` |
 | `HoneycombSink` | `log_foundry.sinks.honeycomb` | — | `HoneycombSink(api_key, dataset, *, url="https://api.honeycomb.io")` |
-| `SentrySink` | `log_foundry.sinks.sentry` | `sentry` | `SentrySink(dsn=None, *, min_level="ERROR")` — sends only `min_level`+ events |
+| `SentrySink` | `log_foundry.sinks.sentry` | `sentry` | `SentrySink(dsn=None, *, min_level="ERROR", backend="auto")` — sends only `min_level`+ events |
 
-With the `sentry` extra installed, `SentrySink` captures via `sentry_sdk.capture_event` (initialize
-the SDK yourself with `sentry_sdk.init(...)`); without it, pass `dsn=` and events are POSTed as
-Sentry envelopes over HTTP.
+`SentrySink` captures via `sentry_sdk.capture_event` when the SDK can deliver — you initialize it
+yourself with `sentry_sdk.init(...)` — and POSTs Sentry envelopes over HTTP to `dsn=` otherwise.
+With neither a deliverable SDK nor a `dsn=`, a batch is **refused** rather than silently dropped.
+`backend=` decides:
+
+| `backend=` | What it uses |
+|---|---|
+| `"auto"` (default) | the SDK when it can deliver, otherwise the HTTP fallback; re-decided on every batch, so an `init(...)` that arrives after the sink was built is picked up |
+| `"sdk"` | the SDK only. A client that cannot deliver **refuses the batch** rather than quietly switching transport |
+| `"http"` | the HTTP fallback only. No SDK is held, consulted or flushed |
+
+"Can deliver" means the SDK's client reports itself active *and* holds a transport. An
+uninitialized process, an `init()` with no DSN, and a `close()`d client all fail that — the first
+reports itself inactive, the other two report themselves active with nothing to send through, and
+all three drop events silently.
+
+An argument the chosen backend can never use is a `ValueError` rather than a silent ignore:
+`opener=` where no HTTP fallback is built, `client=` under `backend="http"`. Until this release
+`opener=` was accepted and then ignored whenever the SDK happened to import — including when it was
+installed as somebody else's transitive dependency.
 
 #### AWS — the durable-buffer path (`aws` extra)
 
@@ -761,7 +778,16 @@ Two things worth knowing:
 
 #### Queue & stream
 
-Each needs its own extra (lazy-imported). All publish + retry within a bound and close cleanly.
+Each needs its own extra (lazy-imported). All publish within a bound and close cleanly. **Where the
+retry lives differs, and it was measured rather than assumed** (SPEC-041 FR-004): the Redis,
+RabbitMQ and Event Hubs sinks retry through `sinks/_retry`, so their backoff is bounded *and* cut
+short by a shutdown. `KafkaSink`, `NATSSink` and `GooglePubSubSink` add no retry loop and need
+none — each hands off locally and returns without waiting, so nothing of theirs holds the single
+drain thread. Their clients retry on their own threads within their own bounds:
+`message.timeout.ms` (5 min default) for Kafka, a 600 s deadline for Pub/Sub, and for NATS a
+JetStream publish bounded by its 5 s ack timeout with no retry at all. `NATSSink` refuses a batch
+outright while its client reports itself disconnected, so a sustained outage moves
+`health().failed_batches` instead of being absorbed.
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
@@ -785,7 +811,7 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
 | `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…")` |
-| `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False)` — JSONB `event` column + extracted columns |
+| `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False, connect_timeout=5)` — JSONB `event` column + extracted columns. Reconnects an **owned** connection the server has closed; a `connection=` you inject is never reopened. `connect_timeout` is passed to libpq explicitly, so it **overrides** any `connect_timeout` in your DSN |
 | `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False)` — MergeTree, columnar insert |
 
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev72"
+version = "0.10.2.dev74"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink
@@ -185,6 +185,12 @@ ignore = [
 # interpolates something it did not generate should still trip it.
 "tests/integration/test_postgres.py" = ["S608"]
 "tests/integration/test_clickhouse.py" = ["S608"]
+# The NATS outage test stops and restarts its own compose service, because "the server went
+# away" is the condition under test and no fake reproduces what the real client does about it.
+# Every argument is a literal or a path this module derives from `__file__`; there is no shell
+# and no caller input. `docker` is resolved from PATH deliberately -- CI and a developer laptop
+# put it in different places.
+"tests/integration/test_nats.py" = ["S603", "S607"]
 # make-sbom.py exists to drive two virtualenvs it creates itself, so subprocess is the whole job.
 # Every argv element is either a literal, a path under a `tempfile.TemporaryDirectory` this script
 # just made, or a value read from the repository's own pyproject.toml / poetry.lock. There is no

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/kafka.py

@@ -53,6 +53,15 @@ class KafkaSink:
     returns without blocking, while the delivery result arrives asynchronously on a callback
     serviced by ``poll()`` and ``flush()``.
 
+    **Retry (SPEC-041 FR-004).** This sink adds none and needs none: ``produce()`` is a local
+    hand-off that returns without waiting — measured at 0.0000 s for three messages against a
+    dead broker — so it never holds the worker's single drain thread, and librdkafka's own retry
+    is bounded by ``message.timeout.ms`` (five minutes by default). Measured: with that set to
+    1500 ms the delivery callback fired at 2.01 s, and at 4000 ms it fired at 4.01 s. SPEC-027's
+    "cut short by a shutdown" governs a wait *between attempts*, and this sink has none to cut —
+    which is also why it deliberately exposes no ``log_foundry_stop_signal`` attribute, since
+    ``_lifecycle.offer_stop_signal`` probes by ``hasattr`` and that absence is the opt-out.
+
     The worst case (SPEC-027 FR-005) is not a retry loop — this sink has none — but its
     ``close()``: one ``flush_timeout`` wait, 10 s at the default, spent **beside**
     ``shutdown()``'s budget rather than from it. ``Worker.shutdown`` joins the drain thread

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/logstash.py

@@ -15,16 +15,44 @@ from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["LogstashSink"]
 
+_BODY_FORMATS = frozenset({"json_array", "ndjson"})
+"""The two HTTP wire forms, validated rather than passed through.
+
+``HTTPSink._body`` branches on ``== "json_array"`` and treats everything else as NDJSON, so a
+typo -- ``"json-array"`` -- would silently ship the exact body FR-003 exists to stop shipping,
+against a destination that cannot parse it. A parameter documented as taking one of two values
+refuses the third.
+"""
+
 
 class LogstashSink:
     """A :class:`~log_foundry.sinks.base.Sink` that ships JSON lines to Logstash (FR-005).
 
-    Two mutually-exclusive modes are chosen at construction: with a URL the batch goes as JSON
-    lines over HTTP, reusing the ``HTTPSink`` core, and with a host and port each event goes as
-    one newline-terminated line over a raw TCP or UDP socket, reusing
+    Two mutually-exclusive modes are chosen at construction: with a URL the batch goes over HTTP,
+    reusing the ``HTTPSink`` core, and with a host and port each event goes as one
+    newline-terminated line over a raw TCP or UDP socket, reusing
     :class:`~log_foundry.sinks._socket.SocketTransport`. Either backend handles its own bounded
     retry and raises on total failure of its own accord, so ``emit`` needs no rule of its own.
 
+    **What the Logstash side must be configured as** (SPEC-041 FR-003). In HTTP mode the default
+    ``body_format="json_array"`` posts a JSON array as ``application/json``, which a **stock**
+    ``http`` input parses into one event per element with no configuration at all. That is a
+    change: this sink used to post NDJSON as ``application/x-ndjson``, which the ``http`` input's
+    default ``additional_codecs`` map (``{"application/json" => "json"}``) does not cover, so the
+    body fell through to the ``plain`` codec. Measured against Logstash 8.15 — a batch of three
+    arrived as **one** event with the whole payload as text in ``message`` and every structured
+    field gone.
+
+    ``body_format="ndjson"`` restores the old wire form, and it is not merely legacy: an input
+    configured ``additional_codecs => {"application/x-ndjson" => "json_lines"}`` -- the documented
+    workaround for the behaviour above -- needs it. That setting **replaces** the default map
+    rather than merging with it, so such an input parses NDJSON correctly and a JSON array
+    incorrectly. The two configurations are mutually exclusive unless the input lists both, which
+    is why the wire form is a parameter rather than a silent change.
+
+    Socket mode is unaffected: it is newline-delimited either way, and a ``tcp``/``udp`` input
+    uses the ``line``/``json_lines`` codec rather than ``additional_codecs``.
+
     In socket mode both IPv4 and IPv6 destinations are supported, over either transport
     (SPEC-031 FR-002): the UDP socket's address family is resolved from ``host`` rather than
     assumed, which is what an unconditional ``AF_INET`` used to make impossible.
@@ -58,6 +86,7 @@ class LogstashSink:
         host: str | None = None,
         port: int | None = None,
         transport: str = "tcp",
+        body_format: str = "json_array",
         timeout: float = 5.0,
         max_retries: int = 3,
         max_datagram_bytes: int = DEFAULT_MAX_DATAGRAM_BYTES,
@@ -70,6 +99,12 @@ class LogstashSink:
           host: The destination host, selecting socket mode.
           port: The destination port, selecting socket mode.
           transport: ``"tcp"`` or ``"udp"``, in socket mode.
+          body_format: ``"json_array"`` (the default) or ``"ndjson"``. It selects the HTTP wire
+            form and has **no effect** in socket mode, which is always newline-delimited — but it
+            is *validated* in both, because a value this class silently ignores in one mode and
+            silently misreads in the other is worse than a refusal. See the class docstring for
+            what each one requires of the Logstash side; ``"ndjson"`` is the escape hatch for an
+            input already configured with ``additional_codecs``.
           timeout: Seconds allowed per request or connection.
           max_retries: Retries the chosen backend makes.
           max_datagram_bytes: In UDP socket mode, the largest datagram to attempt; a frame over
@@ -81,11 +116,17 @@ class LogstashSink:
           None.
 
         Raises:
-          ValueError: If neither a URL nor a host and port were given.
+          ValueError: If neither a URL nor a host and port were given, or if ``body_format`` is
+            neither ``"json_array"`` nor ``"ndjson"``.
         """
+        if body_format not in _BODY_FORMATS:
+            raise ValueError(
+                f"LogstashSink body_format must be one of {sorted(_BODY_FORMATS)}, "
+                f"not {body_format!r}"
+            )
         if url is not None:
             self._http: HTTPSink | None = HTTPSink(
-                url, body_format="ndjson", timeout=timeout, max_retries=max_retries,
+                url, body_format=body_format, timeout=timeout, max_retries=max_retries,
                 **http_kwargs,  # type: ignore[arg-type]
             )
             self._socket: SocketTransport | None = None

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/nats.py

@@ -21,6 +21,31 @@ class NATSSink:
     completion from the synchronous ``emit``, which therefore returns only after the batch is
     handed off. With JetStream enabled it publishes through JetStream for durable
     acknowledgement.
+
+    **Retry and the worst-case delay** (SPEC-041 FR-004). This sink adds no retry loop and needs
+    none: a core ``publish()`` writes into the client's outbound buffer and returns without
+    waiting — measured at 0.00 s for fifty publishes — so it never holds the worker's single
+    drain thread and there is no backoff for a shutdown to cut short. SPEC-027's guarantee is met
+    because there is no wait, not because a wait is bounded. Under JetStream ``publish()`` awaits
+    an ack bounded by the driver's own timeout (5 s by default) and does not retry.
+
+    **A disconnected client is reported, not absorbed** (FR-004 AC-5). That non-blocking publish
+    is exactly what made this sink report success for events that had not left the process: with
+    the server stopped, five successive emits each returned in 0.00 s with ``losses()`` reading
+    all zeros, and when the client's reconnect budget (60 attempts × 2 s by default) ran out
+    first, **one of six events reached the destination with every counter still at zero**. That
+    is SPEC-026 FR-001's shape — a sink the worker believes, so its retry never engages and
+    ``failed_batches`` never moves. ``emit`` now refuses a batch while the client reports itself
+    disconnected.
+
+    The limit is stated rather than overclaimed: ``is_connected`` does not flip the instant the
+    server dies, so the first batch in the window before the client notices is still accepted and
+    still buffered — measured, one of five emits landed in that window. It is the same
+    check-then-act window ``MongoDBSink`` and ``KafkaSink`` already document for their own flags;
+    what the guard ends is the far larger case of an outage that has been going on for any
+    appreciable time. Refusing moves no ``losses()`` counter, per SPEC-032: it is a failure
+    *reported* to the worker rather than one absorbed, and counting both would report one loss
+    twice.
     """
 
     def __init__(
@@ -86,8 +111,38 @@ class NATSSink:
                 raise SinkDeliveryError(
                     f"NATSSink published none of {len(batch)} event(s): the sink is closed"
                 )
+            if not self._is_connected():
+                raise SinkDeliveryError(
+                    f"NATSSink published none of {len(batch)} event(s): "
+                    "the client is disconnected"
+                )
             self._loop.run_until_complete(self._publish_all(batch))
 
+    def _is_connected(self) -> bool:
+        """Reports whether the client can currently put anything on the wire (FR-004 AC-5).
+
+        Probed by name, as ``drain`` and ``flush`` are, because this sink is written against a
+        driver it does not own and accepts an injected ``client=``. A client that does not
+        publish the attribute is assumed connected: the guard exists to convert a *known*
+        non-delivery into a reported one, and inventing a refusal for a client that never
+        claimed to be disconnected would fail batches that were going to succeed.
+
+        Args:
+          None.
+
+        Returns:
+          True when the client reports itself connected, or says nothing about it.
+
+        Raises:
+          None. A driver whose attribute access raises is treated as connected, so a probe can
+            never be the reason a batch fails.
+        """
+        try:
+            connected = getattr(self._client, "is_connected", True)
+        except Exception:
+            return True
+        return bool(connected)
+
     def losses(self) -> SinkLosses:
         """Reports events whose publish raised (SPEC-026 FR-002).
 

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/postgres.py

@@ -15,6 +15,22 @@ __all__ = ["PostgresSink"]
 
 _BACKOFF_BASE = 0.1
 
+DEFAULT_CONNECT_TIMEOUT = 5
+"""Seconds libpq may spend opening one connection (SPEC-041 FR-002).
+
+``psycopg.connect()`` takes no timeout unless one is given, and libpq's default is to wait
+indefinitely. That call runs on the worker's single drain thread, holding this sink's emit lock,
+and it consults no stop signal -- so against a host that blackholes packets rather than refusing
+them it is exactly the unbounded, uninterruptible wait SPEC-027 exists to remove. Measured
+against an unroutable address: **75.01 s** with no timeout, **2.03 s** with ``connect_timeout=2``.
+
+Floored at libpq's own minimum of 2 rather than accepted verbatim, because ``0`` means "wait
+forever" -- reinstating the defect -- the same reason ``KafkaSink._usable_timeout`` refuses its
+own degenerate values (SPEC-038 FR-006).
+"""
+
+_MIN_CONNECT_TIMEOUT = 2
+
 _COLUMNS = ("timestamp", "level", "trace_id", "span_id", "function", "service")
 
 
@@ -23,8 +39,15 @@ class PostgresSink:
 
     Each event is stored as a ``JSONB`` ``event`` column plus a few extracted columns for
     indexing. ``psycopg`` v3 is the optional ``postgres`` extra, imported lazily. The sink is
-    write-only, and the worst-case delay (SPEC-027 FR-005) is ``max_retries`` interruptible waits
-    per batch, 0.7 s at the defaults.
+    write-only. The worst-case delay (SPEC-027 FR-005) has two halves, and only one of them is
+    interruptible. The backoffs are ``max_retries`` waits per batch — 0.7 s at the defaults —
+    taken through ``_retry.wait`` on the worker's stop event, so a shutdown cuts them short. The
+    reconnects are up to ``max_retries + 1`` connects of ``connect_timeout`` each, 20 s more at
+    the defaults, and they are **bounded but not interruptible**: the wait is inside libpq, which
+    consults nothing. That is the settled line rather than a gap — a shutdown shortens a *wait*
+    and never skips *work*, and a reconnect is the work an in-flight batch needs (SPEC-038
+    FR-001 AC-4a). Both halves sit inside the existing retry budget rather than a loop of their
+    own, which is what bounds them (FR-002 AC-3).
 
     The driver requirement satisfied (SPEC-028 FR-002): a ``psycopg`` connection carries one
     transaction, and this sink's unit of work is a ``cursor`` / ``commit`` / ``rollback`` sequence
@@ -48,6 +71,7 @@ class PostgresSink:
         create_table: bool = False,
         chunk_size: int = 1000,
         max_retries: int = 3,
+        connect_timeout: int = DEFAULT_CONNECT_TIMEOUT,
     ) -> None:
         """Connects to the database and prepares the insert statement.
 
@@ -61,6 +85,13 @@ class PostgresSink:
           max_retries: Retries per batch, floored at zero as ``Worker._emit`` floors its own
             (SPEC-021) — a negative value returned having attempted no insert at all, and
             reported success.
+          connect_timeout: Seconds libpq may spend opening a connection. Defaults to
+            :data:`DEFAULT_CONNECT_TIMEOUT` (5) and is floored at libpq's own minimum of 2, since
+            ``0`` means "wait forever" and would reinstate the unbounded connect this argument
+            exists to remove. It is passed explicitly and therefore **overrides any
+            ``connect_timeout`` in the DSN** — a DSN asking for 30 gets this value instead, so
+            set it here rather than there. Applies to the connection opened at construction and
+            to every reconnect.
 
         Returns:
           None.
@@ -78,11 +109,12 @@ class PostgresSink:
         self._lock = threading.Lock()
         self._counter_lock = threading.Lock()
         self._owns_connection = connection is None
+        self._dsn = dsn
+        self.connect_timeout = max(connect_timeout, _MIN_CONNECT_TIMEOUT)
         if connection is None:
-            import psycopg  # type: ignore[import-not-found]
-
-            connection = psycopg.connect(dsn)
+            connection = self._connect()
         self._conn = connection
+        self._reconnect_announced = False
         columns = ", ".join((*_COLUMNS, "event"))
         placeholders = ", ".join(["%s"] * len(_COLUMNS) + ["%s::jsonb"])
         self._insert_sql = f"INSERT INTO {self._table} ({columns}) VALUES ({placeholders})"
@@ -153,6 +185,7 @@ class PostgresSink:
         """
         for attempt in range(self.max_retries + 1):
             try:
+                self._reconnect_if_broken()
                 with self._conn.cursor() as cur:
                     for chunk in chunk_list(batch, self._chunk_size):
                         cur.executemany(self._insert_sql, [self._row(event) for event in chunk])
@@ -168,12 +201,126 @@ class PostgresSink:
                 _diag.lost(
                     "event",
                     len(batch),
-                    f"PostgresSink, {self.max_retries + 1} attempts, {type(err).__name__}",
+                    f"PostgresSink, {self.max_retries + 1} attempts, {type(err).__name__}"
+                    + (
+                        ", borrowed connection is broken and this sink may not reopen it"
+                        if not self._owns_connection and self._is_broken()
+                        else ""
+                    ),
                 )
                 raise SinkDeliveryError(
                     f"PostgresSink inserted none of {len(batch)} event(s)"
                 ) from None
 
+    def _connect(self) -> Any:
+        """Opens a connection to the configured DSN, bounded by :attr:`connect_timeout`.
+
+        The bound is passed as a keyword rather than left to the DSN, so it holds **regardless of**
+        what the caller's connection string says — which is the same fact ``__init__`` states from
+        the caller's side, that this argument overrides a ``connect_timeout`` in the DSN. See
+        :data:`DEFAULT_CONNECT_TIMEOUT` for why an unbounded connect here is the defect rather
+        than the default.
+
+        Args:
+          None.
+
+        Returns:
+          The new connection.
+
+        Raises:
+          ImportError: If the ``postgres`` extra is not installed.
+          Exception: Whatever the driver raises when connecting.
+        """
+        import psycopg  # type: ignore[import-not-found]
+
+        return psycopg.connect(self._dsn, connect_timeout=self.connect_timeout)
+
+    def _reconnect_if_broken(self) -> None:
+        """Replaces an unusable **owned** connection before an insert attempt (FR-002).
+
+        A ``psycopg`` connection is permanently unusable once the server closes it, and this sink
+        opened one in ``__init__`` and never reopened it — so a single restart, failover or idle
+        timeout ended log delivery for the life of the process, with every in-batch retry running
+        against the same dead handle. Measured against a real Postgres: one
+        ``pg_terminate_backend`` and three subsequent batches were lost, one row delivered.
+        Every sibling already recovers (``SocketTransport._reset``, boto3, clickhouse-connect's
+        pool, pymongo's pool).
+
+        **It runs at the top of each attempt, not in the retry branch.** ``max_retries`` is a
+        public argument floored at zero, so a reconnect placed where a retry remains never runs
+        at all at ``max_retries=0`` and the defect would survive at that setting forever. At the
+        top of the attempt, the first emit after a failure reopens — which is FR-002 AC-1
+        literally — at every value. It also avoids spending a connect immediately before the
+        raise, where it can only cost time.
+
+        **A borrowed connection is never reopened**, per ``architecture.md`` §13's borrowed-client
+        constraint: the caller owns that object and its lifetime, and replacing it here would
+        leak theirs and reconnect a session they may be sharing. The exhausted batch's existing
+        ``_diag.lost`` line gains a clause rather than a new stderr site, and it is conditioned on
+        the connection actually being broken — appending it to every borrowed-connection failure
+        would put "not reopened" on a constraint violation, where reopening was never the
+        question.
+
+        The state is read from the connection rather than inferred: ``closed`` and ``broken`` are
+        both ``False`` before the first failure and both ``True`` after it, so an ordinary SQL
+        error — a constraint violation, a full disk — does not churn the connection. Both are
+        probed by name because this sink accepts any ``psycopg``-shaped object it does not own.
+
+Both diagnostics here are **announced once per outage, not once per attempt**. Unthrottled
+        they fire on every attempt of every batch, so a down server turned one stderr line into
+        five per batch, indefinitely — a diagnostic that floods is one an operator stops reading,
+        and the batch's own ``_diag.lost`` line already records the loss. The flag covers the
+        failed ``close()`` as well as the failed connect, because a failed reconnect leaves the
+        old object in place and the next attempt closes it again. It clears on a successful
+        reconnect, so a later outage is announced again.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          None. A failed reconnect is absorbed and left to the next attempt, which is what keeps
+            this inside the existing retry budget rather than adding a loop of its own (AC-3):
+            the batch's bound is unchanged, and a connect that cannot succeed simply spends an
+            attempt visibly, through the counters.
+        """
+        if not self._owns_connection or not self._is_broken():
+            return
+        announced, self._reconnect_announced = self._reconnect_announced, True
+        try:
+            self._conn.close()
+        except Exception as err:
+            if not announced:
+                _diag.absorbed("PostgresSink.close of a broken connection", err)
+        try:
+            self._conn = self._connect()
+            self._reconnect_announced = False
+        except Exception as err:
+            if not announced:
+                _diag.absorbed("PostgresSink.reconnect", err)
+
+    def _is_broken(self) -> bool:
+        """Reports whether the held connection can no longer be used.
+
+        Args:
+          None.
+
+        Returns:
+          True when the driver reports the connection closed or broken.
+
+        Raises:
+          None. A driver whose attribute access raises is treated as usable, so a probe can
+            never be the reason a batch fails.
+        """
+        try:
+            return bool(getattr(self._conn, "closed", False)) or bool(
+                getattr(self._conn, "broken", False)
+            )
+        except Exception:
+            return False
+
     def _rollback(self) -> None:
         """Discards the failed transaction, absorbing a rollback that itself fails (FR-002).
 
@@ -210,6 +357,13 @@ class PostgresSink:
         Idempotent, and takes the emit lock so the final commit never lands in the middle of
         another thread's transaction (SPEC-028 FR-002).
 
+        **The final commit is guarded** (SPEC-041 FR-002). It was unconditional, so a connection
+        the server had closed made ``close()`` raise — reachable without any exotic timing, since
+        a broken connection is only repaired inside an emit attempt and a process that breaks and
+        then shuts down never has another. The release still has to happen, and a commit that
+        cannot reach the server has nothing to publish, so the failure is announced by type and
+        the close proceeds.
+
         Args:
           None.
 
@@ -217,13 +371,16 @@ class PostgresSink:
           None.
 
         Raises:
-          Exception: Whatever the driver raises on commit or close.
+          Exception: Whatever the driver raises on close. The commit no longer escapes.
         """
         with self._lock:
             if self._closed:
                 return
             self._closed = True
-            self._conn.commit()
+            try:
+                self._conn.commit()
+            except Exception as err:
+                _diag.absorbed("PostgresSink.close commit", err)
             if self._owns_connection:
                 self._conn.close()
 

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/pubsub.py

@@ -59,6 +59,14 @@ class GooglePubSubSink:
     imported lazily. ``publish()`` returns a future that resolves asynchronously, so the sink
     accumulates the batch's futures and resolves them on :meth:`close`.
 
+    **Retry (SPEC-041 FR-004).** The client's own retry is bounded and runs on the client's
+    threads, never the worker's drain thread: the generated ``publish`` carries
+    ``Retry(initial=0.1, maximum=60.0, multiplier=4, deadline=600.0)`` with a 60 s per-call
+    timeout, so a publish gives up after ten minutes at the outside. What this sink contributes
+    is the only wait the drain thread ever takes — :meth:`_await_overflow`'s
+    ``overflow_timeout``, bounded and interruptible per SPEC-027. Measured with the destination
+    stopped and ``overflow_timeout=5.0``: every over-bound emit returned in 5.00 s exactly.
+
     The driver requirement satisfied (SPEC-028 FR-002): this sink takes **no** transport lock —
     the publisher client owns its own batching and threading, and ``publish()`` is a local
     hand-off. What it does hold is the pending-futures list, which is genuinely shared between

{log_foundry-0.10.2.dev72 → log_foundry-0.10.2.dev74}/src/log_foundry/sinks/sentry.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import threading
 import uuid
-from typing import Any
+from typing import Any, Final, Literal, get_args
 from urllib.parse import urlparse
 
 from log_foundry import _diag, _lifecycle
@@ -14,6 +14,17 @@ from log_foundry.sinks.http import HTTPSink
 
 __all__ = ["SentrySink"]
 
+Backend = Literal["auto", "sdk", "http"]
+"""Which transport a :class:`SentrySink` uses. Not exported: callers pass the literals."""
+
+_BACKENDS: Final = get_args(Backend)
+
+_Selected = Literal["sdk", "http"]
+"""A backend actually chosen for one batch -- never ``"auto"``, which selects rather than is."""
+
+_ABSENT: Final = object()
+"""Sentinel telling an absent member from one whose value is ``None`` (SPEC-043 FR-001)."""
+
 _LEVEL_RANK = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
 _SENTRY_LEVEL = {
     "DEBUG": "debug", "INFO": "info", "WARNING": "warning", "ERROR": "error", "CRITICAL": "fatal",
@@ -23,12 +34,39 @@ _SENTRY_LEVEL = {
 class SentrySink:
     """A :class:`~log_foundry.sinks.base.Sink` that captures qualifying events to Sentry (FR-011).
 
-    It uses the ``sentry-sdk`` when the optional extra is installed, imported lazily inside the
-    sink so importing this module never requires it. Without the SDK it falls back to POSTing a
-    Sentry envelope over HTTP to the DSN's ingest URL. Only events at or above the configured
-    minimum level are sent.
+    It uses the ``sentry-sdk`` when one is installed *and able to deliver*, imported lazily inside
+    the sink so importing this module never requires it. Otherwise it POSTs a Sentry envelope over
+    HTTP to the DSN's ingest URL. Only events at or above the configured minimum level are sent.
+
+    ``backend`` selects explicitly and ``"auto"`` is the default (SPEC-043 FR-002). An explicit
+    selection is honoured rather than substituted: under ``"sdk"`` a client that cannot deliver is
+    refused, never diverted to HTTP, and under ``"http"`` no client is held, consulted or flushed.
+    What is built, and what each ``emit`` then does:
+
+    ===========  ==========  ======  ==============  ===========  ==================================
+    ``backend``  client?     DSN?    ``self.client`` ``_http``    Per emit
+    ===========  ==========  ======  ==============  ===========  ==================================
+    ``auto``     yes         yes     the client      built        SDK if it can deliver, else HTTP
+    ``auto``     yes         no      the client      ``None``     SDK if it can deliver, else refuse
+    ``auto``     no          yes     ``None``        built        HTTP
+    ``auto``     no          no      —               —            ``ValueError`` at construction
+    ``sdk``      yes         either  the client      ``None``     SDK if it can deliver, else refuse
+    ``sdk``      no          either  —               —            ``ValueError`` at construction
+    ``http``     rejected    yes     ``None``        built        HTTP
+    ``http``     rejected    no      —               —            ``ValueError`` at construction
+    ===========  ==========  ======  ==============  ===========  ==================================
+
+    "Can deliver" is judged once per ``emit``, so an application that initialises the SDK after
+    building this sink starts using it without rebuilding one. An argument whose only consumer is
+    a backend this construction will never select is a ``ValueError`` rather than a silent
+    ignore — ``opener`` where no HTTP fallback is built, ``client`` under ``"http"``. That is the
+    defect this rule comes from: ``opener`` used to be accepted and then ignored whenever the SDK
+    imported. ``max_retries`` is deliberately outside the rule, since its default cannot be told
+    from an explicit pass of the same value.
 
     Attributes:
+      client: The SDK object this sink captures through, or ``None`` when the HTTP fallback is
+        the only backend it can select.
       sent: Events captured or sent to Sentry.
       skipped: Events below the minimum level, or without a usable level, that were not sent.
       transport_errors: Events whose send raised something other than an already-counted
@@ -48,16 +86,29 @@ class SentrySink:
         dsn: str | None = None,
         *,
         min_level: str = "ERROR",
+        backend: Backend = "auto",
         client: Any = None,
         opener: Any = None,
         max_retries: int = 3,
     ) -> None:
         """Selects the SDK or the HTTP-envelope fallback and sets the level floor.
 
+        The order is deliberate: an unknown ``backend`` is rejected first, then the arguments the
+        selection cannot use, then the selections nothing can build. Several constructions trip a
+        conflict *and* a refusal — any of them with no DSN, for instance — and each raises
+        ``ValueError`` either way, so the conflict is reported first because it names an argument
+        the caller can drop, where the refusal only says the selection cannot be built.
+
+        Both backends this construction can select are built here rather than on first use. A
+        fallback built lazily would miss the worker's one-shot ``log_foundry_stop_signal`` offer
+        and stop being interruptible (SPEC-027), and it would rebind transport state inside
+        ``emit``, contradicting this class's SPEC-028 exemption.
+
         Args:
           dsn: The Sentry DSN. It is required for the fallback, which needs it to know where to
             POST.
           min_level: The lowest level worth sending.
+          backend: Which transport to use — ``"auto"``, ``"sdk"`` or ``"http"``.
           client: A ``sentry_sdk``-shaped object to use instead of importing one.
           opener: A ``urlopen``-shaped callable for the fallback, for tests.
           max_retries: Retries the fallback's HTTP transport makes.
@@ -66,22 +117,51 @@ class SentrySink:
           None.
 
         Raises:
-          ValueError: If no SDK is available and no DSN was given.
+          ValueError: If ``backend`` is not one of the three names; if an argument cannot be used
+            by any backend this construction can select; or if the selection cannot be built —
+            ``"sdk"`` with no client available, ``"http"`` with no DSN, or the default with
+            neither.
         """
+        if backend not in _BACKENDS:
+            raise ValueError(f"SentrySink backend must be one of {_BACKENDS!r}, not {backend!r}")
+        if client is not None and backend == "http":
+            raise ValueError(
+                "SentrySink(backend='http') never captures through a client; drop client= or "
+                "select a backend that can use it"
+            )
+        if opener is not None and (backend == "sdk" or dsn is None):
+            remedy = "drop backend='sdk'" if backend == "sdk" else "pass a dsn"
+            raise ValueError(
+                "SentrySink builds no HTTP fallback for this construction, so opener= would "
+                f"never be called; {remedy}"
+            )
         self._dsn = dsn
+        self._backend = backend
         self._min_rank = _LEVEL_RANK.get(min_level.upper(), _LEVEL_RANK["ERROR"])
         self.sent = 0
         self.skipped = 0
         self.transport_errors = 0
         self._counter_lock = threading.Lock()
-        self.client = client if client is not None else _import_sdk()
+        self.client: Any = None if backend == "http" else (
+            client if client is not None else _import_sdk()
+        )
         self._http: HTTPSink | None = None
         self._auth_header = ""
-        if self.client is None:
-            if dsn is None:
+        if backend == "sdk":
+            if self.client is None:
+                raise ValueError(
+                    "SentrySink(backend='sdk') requires the sentry extra or an injected client="
+                )
+        elif dsn is None:
+            if backend == "http":
+                raise ValueError(
+                    "SentrySink(backend='http') requires a dsn for the HTTP-envelope fallback"
+                )
+            if self.client is None:
                 raise ValueError(
                     "SentrySink without sentry-sdk requires a dsn for the HTTP-envelope fallback"
                 )
+        else:
             ingest_url, self._auth_header = _parse_dsn(dsn)
             self._http = HTTPSink(ingest_url, opener=opener, max_retries=max_retries)
         self._stop_signal: threading.Event | None = None
@@ -94,6 +174,9 @@ class SentrySink:
         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.
 
+        The backend is chosen once, before the loop, so one batch cannot split across transports
+        partway through and so the client is probed once rather than per event.
+
         Args:
           batch: The events to consider.
 
@@ -101,10 +184,12 @@ class SentrySink:
           None.
 
         Raises:
-          SinkDeliveryError: If every qualifying event failed to land. An event below the
-            minimum level is skipped rather than lost, so a batch of nothing but skipped events
-            is a successful emit — there was never anything to deliver.
+          SinkDeliveryError: If every qualifying event failed to land, which includes the case
+            where no backend can deliver at all (SPEC-043 FR-003). An event below the minimum
+            level is skipped rather than lost, so a batch of nothing but skipped events is a
+            successful emit — there was never anything to deliver.
         """
+        backend = self._select_backend()
         attempted = delivered = 0
         for event in batch:
             if not self._qualifies(event):
@@ -112,7 +197,7 @@ class SentrySink:
                     self.skipped += 1
                 continue
             attempted += 1
-            if not self._capture(event):
+            if not self._capture(event, backend):
                 continue
             with self._counter_lock:
                 self.sent += 1
@@ -133,7 +218,12 @@ class SentrySink:
         interpreter exit got to it.
 
         Only the injected-or-imported SDK client has a queue. The ``urllib`` fallback posts an
-        envelope per event and holds nothing, so with no client this is correctly a no-op.
+        envelope per event and holds nothing, so with no client this is correctly a no-op — and
+        ``backend="http"`` holds none, which is what keeps this from pushing an application's own
+        Sentry transport on behalf of a sink that never captures through it.
+
+        A client the per-emit predicate currently reads as unable to deliver is still flushed: it
+        may become usable before the next batch, and flushing one that cannot is a no-op anyway.
 
         ``Client.flush`` is probed by name, as every optional member the library calls on an object
         it does not own is: a stand-in ``client=`` satisfying only ``capture_event`` stays valid,
@@ -254,8 +344,20 @@ class SentrySink:
         with self._counter_lock:
             return SinkLosses(dropped=0, failed=self.failed + self.transport_errors)
 
-    def _capture(self, event: dict[str, object]) -> bool:
-        """Sends one event by whichever transport is configured.
+    def _capture(self, event: dict[str, object], backend: _Selected | None) -> bool:
+        """Sends one event by the backend ``emit`` resolved for this batch.
+
+        A ``None`` backend is refused here, before the ``try``, and moves nothing. Letting it fall
+        into the envelope branch instead would reach ``_post_envelope``'s assertion, whose
+        ``AssertionError`` the guard below counts as a ``transport_errors`` and announces through
+        ``_diag`` — both forbidden for a refusal (SPEC-043 FR-003), because the caller is told by
+        the ``SinkDeliveryError`` ``emit`` raises and counting it here would report one loss twice.
+        The refusal stays inside the per-event loop so the level filter keeps running ahead of it
+        and the raise names the qualifying count.
+
+        The branch is on the resolved name rather than on ``self.client is not None``: that
+        condition is still true under ``"auto"`` when the client cannot deliver, so it would take
+        the SDK branch anyway and preserve the very defect this selection exists to fix.
 
         One guard covers both branches, catching ``Exception`` rather than an enumerated set.
         Anything escaping here propagates mid-batch and hands the worker a batch Sentry has
@@ -267,6 +369,7 @@ class SentrySink:
 
         Args:
           event: The event to send.
+          backend: The backend ``emit`` resolved, or ``None`` when nothing can deliver.
 
         Returns:
           True when it landed, False when it did not.
@@ -276,8 +379,10 @@ class SentrySink:
             has already counted and announced it, and counting it again would double-report.
             Only the exception type is ever written (arch §6).
         """
+        if backend is None:
+            return False
         try:
-            if self.client is not None:
+            if backend == "sdk":
                 self.client.capture_event(self._sentry_event(event))
             else:
                 self._post_envelope(event)
@@ -290,6 +395,76 @@ class SentrySink:
             return False
         return True
 
+    def _select_backend(self) -> _Selected | None:
+        """Picks the transport for one batch, or ``None`` when nothing can deliver.
+
+        An explicit selection is honoured rather than substituted (SPEC-043 FR-002): ``"sdk"``
+        against a client that cannot deliver returns ``None`` so the batch is refused, because a
+        caller who named a backend and got a different one is this sink's original defect in a
+        new place. ``"http"`` never consults the client, which is what keeps a held-but-unusable
+        SDK out of the decision entirely.
+
+        Args:
+          None.
+
+        Returns:
+          ``"sdk"``, ``"http"``, or ``None`` when neither backend can deliver.
+
+        Raises:
+          None.
+        """
+        if self._backend == "http":
+            return "http"
+        if self.client is not None and self._client_can_deliver():
+            return "sdk"
+        if self._backend == "sdk":
+            return None
+        return "http" if self._http is not None else None
+
+    def _client_can_deliver(self) -> bool:
+        """Reports whether the held client has somewhere to send, not merely that it exists.
+
+        Three states cannot deliver and only one of them reports itself inactive: an
+        uninitialised process holds a ``NonRecordingClient`` (``is_active()`` false), while
+        ``init()`` without a DSN and a client that has been ``close()``d both report themselves
+        active with a ``None`` transport and drop every event silently. So the predicate takes
+        both members, and it is the transport that binds — ``is_active()`` is a hardcoded class
+        discriminator, kept because it is the SDK's documented answer and a future client may
+        diverge, not because anything here can distinguish it from the transport alone.
+
+        It descends first: ``__init__`` holds the ``sentry_sdk`` **module**, which publishes
+        neither member, so a probe that read the held object would call the defective path usable
+        and leave the defect in place. ``is_active`` is *called* rather than read, since a bound
+        method is truthy and reading one yields a guard that can never fail; a non-callable
+        ``is_active`` is treated as absent instead. Absence means usable throughout, which is what
+        keeps an injected double, a pre-SPEC-043 client and a pre-2.0 SDK working — hence the
+        sentinel, since an absent ``transport`` and a ``None`` one are opposite answers.
+
+        Args:
+          None.
+
+        Returns:
+          True when the client is worth capturing through.
+
+        Raises:
+          None. A probe may never be the reason a batch fails (SPEC-025), so a client that raises
+            while being questioned is treated as usable and the fault is announced by type.
+        """
+        try:
+            target = self.client
+            descend = getattr(target, "get_client", None)
+            if callable(descend):
+                descended = descend()
+                if descended is not None:
+                    target = descended
+            is_active = getattr(target, "is_active", None)
+            if callable(is_active) and not is_active():
+                return False
+            return getattr(target, "transport", _ABSENT) is not None
+        except Exception as err:
+            _diag.absorbed("probing the Sentry client", err, "it is treated as usable")
+            return True
+
     def _qualifies(self, event: dict[str, object]) -> bool:
         """Reports whether an event is at or above the configured level floor.
 
@@ -334,7 +509,9 @@ class SentrySink:
         """POSTs one event as a Sentry envelope over the HTTP fallback.
 
         The assertion narrows the type for mypy rather than checking at runtime: the HTTP
-        transport is set in the constructor whenever the path that reaches here is in use.
+        transport is set in the constructor whenever the path that reaches here is in use, which
+        is true because ``_capture`` refuses a ``None`` backend before reaching this branch and
+        ``_select_backend`` only answers ``"http"`` where one was built.
 
         Args:
           event: The event to send.