log-foundry 0.10.2.dev25__tar.gz → 0.10.2.dev27__tar.gz

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev25
+Version: 0.10.2.dev27
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -234,6 +234,34 @@ lf.configure(
 If you never set a `sink`, the first decorated call falls back to `StdoutSink()`, so `@trace`
 works with zero configuration.
 
+**Passing `sink=` after logging has started swaps the live destination.** The background worker
+captures its sink when it is built, so a later `configure(sink=...)` has to do more than update
+what `get_config()` reports — otherwise the config and the behaviour disagree silently, which is
+what it used to do. The swap drains everything submitted so far to the **previous** sink, closes
+it, and points the worker at the new one:
+
+```python
+lf.configure(sink=StdoutSink())
+do_some_work()                       # these events go to stdout
+
+lf.configure(sink=SQSSink(queue_url=QUEUE_URL))
+do_some_more_work()                  # these go to SQS; the earlier ones were drained to stdout
+```
+
+The drain is bounded at 5 s. If it cannot be confirmed in that time the swap still takes effect —
+you asked for that sink — but the previous sink is left **open** rather than closed, because the
+drain thread may still be inside its `emit`, and `health().incomplete_swaps` records it. Passing
+the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
+do not hand it back to a later call.
+
+The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
+a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
+an unreachable broker is the case to watch. Configure the sink before the first log where you can;
+that path has no worker to retarget and nothing to close.
+
+`configure()` is still a startup call. It is not thread-safe, and a span finishing on another
+thread mid-swap may land on either sink.
+
 ### `@trace`
 
 Decorate any **synchronous** function. Usable bare or with arguments:
@@ -668,7 +696,7 @@ in `CallbackSink`.
 
 #### Writing your own sink
 
-`Sink` is two required methods, `emit(batch)` and `close()`, plus two rules about *how* `emit`
+`Sink` is two required methods, `emit(batch)` and `close()`, plus three rules about *how* `emit`
 fails and one about *when* it is called. They are not stylistic — the library's whole
 loss-reporting apparatus is built on them:
 
@@ -688,6 +716,15 @@ loss-reporting apparatus is built on them:
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
+- **Raise after your own `close()`, if `close()` released anything.** A batch handed to a
+  released transport has delivered nothing, so it is the first rule again by another route — and
+  it is easy to miss, because the sink looks like it worked. Three of the shipped sinks got this
+  wrong for four releases: one accepted a produce into a client buffer nothing would flush again,
+  one appended a delivery future nothing would resolve, and one transparently *reconnected*,
+  leaking a connection nothing would reap. Set the flag before you release, and read it in `emit`.
+  If your `close()` releases nothing — you open a fresh connection per request, or the client is
+  the caller's — then **keep accepting**: refusing a batch you would have delivered is loss you
+  invented. `emit([])` stays a no-op either way.
 
 A sink that absorbs a total failure and returns normally is a sink the worker believes: the retry
 never engages, `failed_batches` stays at zero, and `flush()` returns `True` while every event is
@@ -704,12 +741,19 @@ from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 class MySink:
     def __init__(self) -> None:
         self._dropped = self._failed = 0
+        self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
 
     def emit(self, batch: list[dict[str, object]]) -> None:
+        if not batch:
+            return
         delivered = 0
         with self._lock:                       # your connection, socket or stream
+            if self._closed:                   # refuse: nothing here can deliver it
+                raise SinkDeliveryError(
+                    f"MySink delivered none of {len(batch)} event(s): the sink is closed"
+                )
             for chunk in self._chunks(batch):
                 if self._send(chunk):          # your own bounded retry
                     delivered += len(chunk)
@@ -725,6 +769,9 @@ class MySink:
 
     def close(self) -> None:
         with self._lock:                       # never release under an active writer
+            if self._closed:                   # idempotent: atexit races your own cleanup
+                return
+            self._closed = True                # set the flag, *then* release
             ...
 ```
 
@@ -746,7 +793,11 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
+if (
+    h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps
+    or (h.sink and (h.sink.dropped or h.sink.failed))
+    or (h.retired and h.submitted_after_shutdown)
+):
     ...  # logs were silently lost — worth an alert
 ```
 
@@ -759,6 +810,8 @@ They tell you different things, and they want different responses:
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+| `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
+| `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -780,8 +833,14 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
+`retired` is deliberately **not** alerted on by itself. A process that shuts down and then stops
+logging is doing the right thing; it is the *pair* — retired, and still being handed events — that
+means every log line since the shutdown has gone nowhere. That state used to read as perfectly
+healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
-fields over time — a fourth (`stopped_reason`) in `v0.7.0` and a fifth (`sink`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
+seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 
@@ -859,6 +918,13 @@ getting them wrong is silent:
   the first invocation on a warm container would log and every later one would silently log
   nothing. That failure reads as "works locally, broken in production".
 
+  It is no longer silent. Logging after `shutdown()` is accepted and undeliverable, and
+  `health()` says so: **`retired` is `True` and `submitted_after_shutdown` is non-zero** — that
+  pair, and only that pair, is this mistake. The first such submission also writes one stderr
+  line naming `flush()` as the remedy, throttled to the first and every thousandth after it.
+  `stopped_reason` stays `None` throughout, because nothing failed; someone used the terminal
+  drain where the repeatable one belonged.
+
 ```python
 import log_foundry as lf
 from log_foundry.sinks.sqs import SQSSink
@@ -876,9 +942,11 @@ def handler(event, context):
         # would log nothing.
         drained = lf.flush()
         h = lf.health()
-        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason or h.retired:
             # `drained` covers this invocation's tail; the counters cover anything the worker
             # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # `h.retired` catches the mistake above: inside a handler it can only mean something
+            # called shutdown(), and from here on this container logs nothing.
             # Emitting this through your platform's own logger keeps it outside the pipeline
             # that just failed.
             print(f"log-foundry: undelivered logs ({drained=}, {h=})")

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/README.md

@@ -198,6 +198,34 @@ lf.configure(
 If you never set a `sink`, the first decorated call falls back to `StdoutSink()`, so `@trace`
 works with zero configuration.
 
+**Passing `sink=` after logging has started swaps the live destination.** The background worker
+captures its sink when it is built, so a later `configure(sink=...)` has to do more than update
+what `get_config()` reports — otherwise the config and the behaviour disagree silently, which is
+what it used to do. The swap drains everything submitted so far to the **previous** sink, closes
+it, and points the worker at the new one:
+
+```python
+lf.configure(sink=StdoutSink())
+do_some_work()                       # these events go to stdout
+
+lf.configure(sink=SQSSink(queue_url=QUEUE_URL))
+do_some_more_work()                  # these go to SQS; the earlier ones were drained to stdout
+```
+
+The drain is bounded at 5 s. If it cannot be confirmed in that time the swap still takes effect —
+you asked for that sink — but the previous sink is left **open** rather than closed, because the
+drain thread may still be inside its `emit`, and `health().incomplete_swaps` records it. Passing
+the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
+do not hand it back to a later call.
+
+The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
+a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
+an unreachable broker is the case to watch. Configure the sink before the first log where you can;
+that path has no worker to retarget and nothing to close.
+
+`configure()` is still a startup call. It is not thread-safe, and a span finishing on another
+thread mid-swap may land on either sink.
+
 ### `@trace`
 
 Decorate any **synchronous** function. Usable bare or with arguments:
@@ -632,7 +660,7 @@ in `CallbackSink`.
 
 #### Writing your own sink
 
-`Sink` is two required methods, `emit(batch)` and `close()`, plus two rules about *how* `emit`
+`Sink` is two required methods, `emit(batch)` and `close()`, plus three rules about *how* `emit`
 fails and one about *when* it is called. They are not stylistic — the library's whole
 loss-reporting apparatus is built on them:
 
@@ -652,6 +680,15 @@ loss-reporting apparatus is built on them:
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
+- **Raise after your own `close()`, if `close()` released anything.** A batch handed to a
+  released transport has delivered nothing, so it is the first rule again by another route — and
+  it is easy to miss, because the sink looks like it worked. Three of the shipped sinks got this
+  wrong for four releases: one accepted a produce into a client buffer nothing would flush again,
+  one appended a delivery future nothing would resolve, and one transparently *reconnected*,
+  leaking a connection nothing would reap. Set the flag before you release, and read it in `emit`.
+  If your `close()` releases nothing — you open a fresh connection per request, or the client is
+  the caller's — then **keep accepting**: refusing a batch you would have delivered is loss you
+  invented. `emit([])` stays a no-op either way.
 
 A sink that absorbs a total failure and returns normally is a sink the worker believes: the retry
 never engages, `failed_batches` stays at zero, and `flush()` returns `True` while every event is
@@ -668,12 +705,19 @@ from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 class MySink:
     def __init__(self) -> None:
         self._dropped = self._failed = 0
+        self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
 
     def emit(self, batch: list[dict[str, object]]) -> None:
+        if not batch:
+            return
         delivered = 0
         with self._lock:                       # your connection, socket or stream
+            if self._closed:                   # refuse: nothing here can deliver it
+                raise SinkDeliveryError(
+                    f"MySink delivered none of {len(batch)} event(s): the sink is closed"
+                )
             for chunk in self._chunks(batch):
                 if self._send(chunk):          # your own bounded retry
                     delivered += len(chunk)
@@ -689,6 +733,9 @@ class MySink:
 
     def close(self) -> None:
         with self._lock:                       # never release under an active writer
+            if self._closed:                   # idempotent: atexit races your own cleanup
+                return
+            self._closed = True                # set the flag, *then* release
             ...
 ```
 
@@ -710,7 +757,11 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
+if (
+    h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps
+    or (h.sink and (h.sink.dropped or h.sink.failed))
+    or (h.retired and h.submitted_after_shutdown)
+):
     ...  # logs were silently lost — worth an alert
 ```
 
@@ -723,6 +774,8 @@ They tell you different things, and they want different responses:
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+| `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
+| `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -744,8 +797,14 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
+`retired` is deliberately **not** alerted on by itself. A process that shuts down and then stops
+logging is doing the right thing; it is the *pair* — retired, and still being handed events — that
+means every log line since the shutdown has gone nowhere. That state used to read as perfectly
+healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
+
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
-fields over time — a fourth (`stopped_reason`) in `v0.7.0` and a fifth (`sink`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
+seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 
@@ -823,6 +882,13 @@ getting them wrong is silent:
   the first invocation on a warm container would log and every later one would silently log
   nothing. That failure reads as "works locally, broken in production".
 
+  It is no longer silent. Logging after `shutdown()` is accepted and undeliverable, and
+  `health()` says so: **`retired` is `True` and `submitted_after_shutdown` is non-zero** — that
+  pair, and only that pair, is this mistake. The first such submission also writes one stderr
+  line naming `flush()` as the remedy, throttled to the first and every thousandth after it.
+  `stopped_reason` stays `None` throughout, because nothing failed; someone used the terminal
+  drain where the repeatable one belonged.
+
 ```python
 import log_foundry as lf
 from log_foundry.sinks.sqs import SQSSink
@@ -840,9 +906,11 @@ def handler(event, context):
         # would log nothing.
         drained = lf.flush()
         h = lf.health()
-        if not drained or h.failed_batches or h.dropped or h.stopped_reason:
+        if not drained or h.failed_batches or h.dropped or h.stopped_reason or h.retired:
             # `drained` covers this invocation's tail; the counters cover anything the worker
             # lost earlier — a batch its own interval trigger already gave up on, for instance.
+            # `h.retired` catches the mistake above: inside a handler it can only mean something
+            # called shutdown(), and from here on this container logs nothing.
             # Emitting this through your platform's own logger keeps it outside the pipeline
             # that just failed.
             print(f"log-foundry: undelivered logs ({drained=}, {h=})")

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/pyproject.toml

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

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/__init__.py

@@ -58,22 +58,35 @@ def health() -> Health:
     code non-blocking, and a non-zero ``failed_batches`` means a sink stayed broken through the
     whole retry budget — both are losses the library absorbs on purpose, and this is how you
     notice them. A non-``None`` ``stopped_reason`` is worse than either: the background thread
-    died on that exception type, so nothing further will be delivered at all (SPEC-019)::
+    died on that exception type, so nothing further will be delivered at all (SPEC-019). A
+    ``retired`` worker still being handed events is the same total loss arrived at from the
+    other direction — someone called :func:`shutdown` in a process that logs again (SPEC-030)::
 
         h = log_foundry.health()
-        if h.dropped or h.failed_batches or h.stopped_reason or (
+        if h.dropped or h.failed_batches or h.stopped_reason or h.incomplete_swaps or (
             h.sink and (h.sink.dropped or h.sink.failed)
-        ):
+        ) or (h.retired and h.submitted_after_shutdown):
             ...  # raise an alert; logs were silently lost
 
+    ``retired`` alone is not a fault — a process that shuts down and then stops logging is
+    doing the right thing, which is why it is paired with the count rather than alerted on.
+
     Args:
       None.
 
     Returns:
-      The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason`` and
-      ``sink``. The last is the configured sink's own
+      The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason``, ``sink``,
+      ``retired``, ``submitted_after_shutdown`` and ``incomplete_swaps``. ``retired`` says
+      :func:`shutdown` was called, and ``submitted_after_shutdown`` counts events accepted
+      afterwards, which are queued where nothing will drain them — non-zero together, that is
+      the ``shutdown()``-per-invocation mistake, and the remedy is :func:`flush`.
+      ``incomplete_swaps`` counts late ``configure(sink=...)`` calls whose drain of the
+      previous sink could not be confirmed, leaving that sink open. ``sink`` is the configured
+      sink's own
       :class:`~log_foundry.sinks.base.SinkLosses` — loss the sink absorbed rather than the
       worker (SPEC-026) — and is ``None`` when no worker exists or the sink reports nothing.
+      Note ``sink`` describes whichever sink is live now, so a swap takes the previous sink's
+      absorbed losses out of the snapshot with it.
       Its ``dropped`` is not the worker's: the worker's is backpressure at the queue, the
       sink's is an event that never reached the wire, and the stderr line names which. Its
       ``failed`` is an upper bound on loss rather than a count of it, since a sink that raises
@@ -98,6 +111,11 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     registered via ``atexit``, so call it explicitly only when you want to be certain the tail
     of the queue reached the sink before a fast process exit (SPEC-004 FR-005).
 
+    Logging afterwards is **accepted and undeliverable**: those events are queued and nothing
+    will drain them. It is not silent any more — :func:`health` then reports ``retired`` with a
+    non-zero ``submitted_after_shutdown``, and the first such submission writes one stderr line
+    (SPEC-030). That pair is the reading that catches the mistake above.
+
     Args:
       timeout: Seconds bounding the wait for the background thread (SPEC-027 FR-004). ``None``
         waits indefinitely, which is what this did unconditionally before and is still

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/config.py

@@ -76,11 +76,31 @@ def configure(
     the zero-dependency dev default (arch §8). Every ceiling is validated before anything is
     assigned, so a rejected call leaves the config exactly as it found it.
 
+    A ``sink=`` passed after logging has already started is the one argument that needs more
+    than an assignment, because the background worker captured its sink when it was built
+    (arch §7). It **swaps the live delivery target**: everything submitted so far is drained to
+    the previous sink, that sink is closed, and subsequent events go to the new one. The drains
+    are bounded, and a swap whose drain could not be confirmed leaves the previous sink open and
+    records ``health().incomplete_swaps`` (SPEC-030 FR-003) — so "repeated calls compose rather
+    than reset" holds for the sink too, at the cost of one bounded wait. Passing the sink that
+    is already live is a no-op: no drain, no close. The previous sink is closed and must not be
+    handed back to a later call.
+
+    The *closing* of the previous sink is not bounded, because ``Sink.close`` takes no timeout —
+    a destination that blocks in ``close()`` blocks this call. It is the same gap
+    ``architecture.md`` §13 already records for ``shutdown()``, and it has the same fix, which
+    is a change to the sink contract rather than to this function.
+
+    This is still a startup call. It is not thread-safe, and a span finishing on another thread
+    during a swap may land on either sink.
+
     Args:
       service: The service name stamped onto every event.
       version: The service version stamped onto every event.
       env: The deployment environment stamped onto every event.
-      sink: The destination every event is delivered to.
+      sink: The destination every event is delivered to. Passed after the first log, it swaps
+        the live target as described above rather than only updating what ``get_config()``
+        reports.
       defaults: Fields merged into every event at the lowest precedence.
       max_value_bytes: Per-value ceiling, in UTF-8 bytes or rendered digits.
       max_stack_bytes: Ceiling for ``error.stack`` alone.
@@ -119,6 +139,37 @@ def configure(
 
     _ensure_sink()
 
+    if sink is not None:
+        _swap_live_sink(sink)
+
+
+def _swap_live_sink(sink: Sink) -> None:
+    """Points an already-running worker at a newly configured sink (SPEC-030 FR-003).
+
+    The import is local for the reason ``_ensure_sink``'s is: ``decorator`` imports this module
+    at module scope, so reaching back the other way at import time would be a cycle. It also
+    keeps the dependency to the one call that needs it — ``configure()`` without a ``sink=``
+    never touches the worker at all.
+
+    The budget is passed explicitly rather than left to the parameter default, so that the
+    bound this call actually applies is resolved when it runs. A default argument is bound at
+    definition time, which would leave the end-to-end bound untestable without reaching past
+    the function under test.
+
+    Args:
+      sink: The sink just written to the config.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    from log_foundry.decorator import _swap_sink
+    from log_foundry.worker import DEFAULT_SWAP_TIMEOUT
+
+    _swap_sink(sink, DEFAULT_SWAP_TIMEOUT)
+
 
 def get_config() -> Config:
     """Returns the current global config singleton.

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/decorator.py

@@ -20,11 +20,13 @@ from log_foundry.ids import (
     parse_traceparent,
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
-from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health, Worker
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_SWAP_TIMEOUT, Health, Worker
 
 if TYPE_CHECKING:
     import contextvars
 
+    from log_foundry.sinks.base import Sink
+
 __all__ = ["continue_trace", "trace"]
 
 _worker: Worker | None = None
@@ -231,6 +233,37 @@ def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
         _worker.shutdown(timeout)
 
 
+def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
+    """Retargets the process worker at a new sink, backing a late ``configure(sink=...)``.
+
+    Like :func:`_flush_worker` this deliberately does not call :func:`_get_worker`: a process
+    that has not logged has captured no sink, so there is nothing to swap and building a thread
+    to prove it would be pure cost — that is also the case where the old behaviour was already
+    correct (SPEC-030 FR-003).
+
+    Args:
+      new_sink: The sink already written to the config, to be made the live delivery target.
+      timeout: Seconds bounding the drain of the previous sink.
+
+    Returns:
+      None.
+
+    Raises:
+      None. This runs inside ``configure()``, which has never raised for anything but a
+        rejected ceiling, and a sink swap that fails must not become the reason an application
+        cannot start.
+    """
+    worker = _worker
+    if worker is None:
+        return
+    try:
+        worker.swap_sink(new_sink, timeout)
+    except Exception as exc:
+        _diag.absorbed(
+            "swapping the log sink", exc, "events may still be delivered to the previous sink"
+        )
+
+
 def _flush_worker(timeout: float | None = 5.0) -> bool:
     """Drains the process worker without retiring it, backing ``flush()`` (SPEC-013 FR-003).
 

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/base.py

@@ -94,9 +94,25 @@ class Sink(Protocol):
         re-delivered wholesale by the worker's retry, and duplicates downstream are worse than
         the counted loss (SPEC-017 FR-004, SPEC-018). Report that through ``losses()`` instead.
 
+        **After ``close()`` has released or invalidated something, raise rather than absorb**
+        (SPEC-032 FR-002). This is the same obligation applied to the sink's own lifecycle
+        rather than the destination's: an absorbed batch is one the worker believes, so the
+        retry never engages, ``failed_batches`` stays at zero and ``flush()`` returns True while
+        the events are gone — reached not through a destination that is down but through a
+        transport the library itself has already let go. Three shipped sinks failed this rule
+        for four specs, in three different ways: a produce into a batch nothing would flush
+        again, a future nothing would resolve, and a client that quietly reconnected.
+
+        The converse is equally binding: a sink holding nothing to release **keeps accepting**.
+        ``close()`` on a sink that opens a fresh connection per request, or whose client belongs
+        to the caller, has invalidated nothing, so a later batch still delivers and refusing it
+        would be loss the library invented rather than loss it reported. Which of the two
+        applies is a property of the sink, so each shipped sink records its answer in its class
+        docstring and a test holds it to it.
+
         Args:
           batch: The events to ship. ``emit([])`` is a no-op and never raises, since an empty
-            batch has not failed to deliver.
+            batch has not failed to deliver — closed or not.
 
         Returns:
           None.
@@ -116,6 +132,12 @@ class Sink(Protocol):
         succeeding. Taking the same lock ``emit`` takes satisfies this; so does an idempotent
         guard checked under that lock.
 
+        The flag this sets is the one a later :meth:`emit` reads, so the two are one decision
+        rather than two (SPEC-032 FR-002). Set it *before* releasing anything: an emit arriving
+        during a release must be refused rather than handed a half-released transport. Make the
+        release idempotent for the same reason a second ``close()`` is expected at all —
+        ``atexit`` racing a caller's own cleanup is the documented case.
+
         Args:
           None.
 

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/callback.py

@@ -17,6 +17,11 @@ class CallbackSink:
     function, without writing a ``Sink`` implementation. Attributes are internal; the observable
     contract is that ``emit`` hands the batch to the callable unchanged and ``close`` invokes
     the close hook once when one was supplied.
+
+    It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
+    (SPEC-032 FR-003). Both decisions belong to the callable: this class holds nothing, and what
+    a hook releases is not knowable from here — a callable needing either guarantee must provide
+    it, exactly as a hand-written ``Sink`` implementation would.
     """
 
     def __init__(

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/datadog.py

@@ -16,6 +16,10 @@ class DatadogSink(HTTPSink):
 
     The batch goes as a JSON array to the region-specific intake with a ``DD-API-KEY`` header,
     each entry enriched with ``ddsource``, ``service`` and ``ddtags``.
+
+    It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
+    (SPEC-032 FR-003), for the reasons :class:`~log_foundry.sinks.http.HTTPSink` records: there
+    is no transport held and ``close()`` releases nothing.
     """
 
     def __init__(

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/elasticsearch.py

@@ -25,6 +25,10 @@ class ElasticsearchSink(HTTPSink):
       dropped_unadjudicated: Events whose outcome a ``_bulk`` response did not describe, because
         its ``items`` array did not line up with the batch sent. Abandoned rather than retried,
         for SPEC-018's reason: the request succeeded, so re-sending would duplicate what landed.
+
+    It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
+    (SPEC-032 FR-003), for the reasons :class:`~log_foundry.sinks.http.HTTPSink` records: there
+    is no transport held and ``close()`` releases nothing.
     """
 
     def __init__(self, url: str, *, index: str, auth: str | tuple[str, str] | None = None,

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/filtering.py

@@ -24,6 +24,10 @@ class FilteringSink:
     This is a static, emit-time filter in front of an inner sink, not the reserved
     tail-sampling ``should_send`` seam (arch §10) — that stays deferred and owns rate policy at
     span-decision time, while this only reshapes an already-built batch on its way to a sink.
+
+    It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
+    (SPEC-032 FR-003): it holds no transport and its ``close()`` only forwards, so both decisions
+    belong to the inner sink. A guard here would refuse batches the inner sink would have taken.
     """
 
     def __init__(

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/firehose.py

@@ -36,6 +36,10 @@ class FirehoseSink:
     The driver requirement satisfied (SPEC-028 FR-002): this sink takes **no** transport
     lock. ``boto3`` clients are documented thread-safe, this one is built once in
     ``__init__``, and the sink rebinds nothing after construction.
+
+    It also **adds no post-close guard** (SPEC-032 FR-003): ``close()`` is a documented no-op,
+    because the client is the caller's to release or the SDK's to reap, so a batch emitted
+    afterwards still reaches the delivery stream.
     """
 
     MAX_RECORDS = 500

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/honeycomb.py

@@ -14,6 +14,10 @@ class HoneycombSink(HTTPSink):
 
     The request goes to ``/1/batch/<dataset>`` with an ``X-Honeycomb-Team`` header, in
     Honeycomb's ``[{"data": <event>}, ...]`` batch shape.
+
+    It takes **no** transport lock (SPEC-028 FR-002) and **adds no post-close guard**
+    (SPEC-032 FR-003), for the reasons :class:`~log_foundry.sinks.http.HTTPSink` records: there
+    is no transport held and ``close()`` releases nothing.
     """
 
     def __init__(

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev27}/src/log_foundry/sinks/http.py

@@ -74,6 +74,13 @@ class HTTPSink:
       failed: Requests abandoned past the retry bound.
       dropped_oversized: Events dropped for exceeding a destination's hard size limit, used by
         subclasses that enforce one; the generic core imposes no universal limit.
+
+    The two lifecycle decisions this class records, inherited by every platform subclass. It
+    takes **no** transport lock (SPEC-028 FR-002): there is no transport to guard, since
+    ``urllib`` opens a fresh connection per request and nothing is rebound after construction.
+    And it **adds no post-close guard** (SPEC-032 FR-003), because ``close()`` releases nothing —
+    a batch emitted afterwards still reaches the endpoint, and refusing it would be loss the
+    library invented rather than loss it reported.
     """
 
     def __init__(