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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev25
+Version: 0.10.2.dev26
 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:
@@ -746,7 +774,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 +791,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 +814,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 +899,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 +923,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.dev26}/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:
@@ -710,7 +738,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 +755,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 +778,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 +863,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 +887,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.dev26}/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.dev26"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev25 → log_foundry-0.10.2.dev26}/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.dev26}/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.dev26}/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.dev26}/src/log_foundry/worker.py

@@ -26,6 +26,14 @@ and an unbounded join there is a hung process.
 
 _DROP_WARN_EVERY = 1000
 
+DEFAULT_SWAP_TIMEOUT = 5.0
+"""Seconds a late ``configure(sink=...)`` will spend draining the previous sink (FR-003).
+
+Shorter than the shutdown budget on purpose: this runs on the caller's thread inside a
+configuration call, where a long stall is a startup that appears to hang, and what is at risk
+is a sink swap rather than the tail of the whole process.
+"""
+
 
 def _bounded_seconds(timeout: float | None) -> str:
     """Renders a shutdown timeout for a diagnostic without trusting its ``__str__``.
@@ -52,9 +60,10 @@ def _bounded_seconds(timeout: float | None) -> str:
 class Health(NamedTuple):
     """A point-in-time snapshot of the worker's delivery counters (SPEC-017 FR-005).
 
-    ``stopped_reason`` and ``sink`` are defaulted and appended in that order, so the zeroed
-    snapshot in ``decorator._worker_health`` — and any third-party construction — keeps
-    working, and attribute and index access to every earlier field stays as it was.
+    ``stopped_reason``, ``sink``, and SPEC-030's three are defaulted and appended in that
+    order, so the zeroed snapshot in ``decorator._worker_health`` — and any third-party
+    construction — keeps working, and attribute and index access to every earlier field stays
+    as it was.
 
     Attributes:
       queued: Submissions currently buffered. Approximate by nature: it is read without
@@ -72,6 +81,25 @@ class Health(NamedTuple):
         the sink reports nothing (SPEC-026 FR-003). Nested rather than folded into the
         integers above because they count different things: ``dropped`` here is backpressure
         at this queue, ``dropped`` on the sink is an event that never reached the wire.
+      retired: Whether :meth:`Worker.shutdown` has been called. It describes an action the
+        caller took, not a failure the library detected, which is why it is a boolean where
+        ``stopped_reason`` is a string — SPEC-019 rejected an ``alive`` flag because it would
+        read ``False`` for a process that never logged, and that objection does not apply to a
+        field which is simply ``False`` until someone calls ``shutdown()`` (SPEC-030 FR-001).
+        On its own it is not a fault: a process that shuts down and stops logging is correct.
+      submitted_after_shutdown: Submissions accepted after ``shutdown()`` and queued where
+        nothing will drain them. Non-zero alongside ``retired`` is the signature of the
+        serverless mistake — ``shutdown()`` called per invocation on a warm container, so the
+        first invocation logs and every later one silently does not. The count starts at the
+        moment ``shutdown()`` begins rather than when the drain thread ends, so a submission
+        racing the final drain is counted even if that drain carried it; erring toward
+        reporting is the right direction for a signal whose whole purpose is visibility.
+      incomplete_swaps: Late ``configure(sink=...)`` calls whose drain of the previous sink
+        did not complete (SPEC-030 FR-003). The swap still took effect, so the caller has the
+        sink it asked for, but two things could not be guaranteed: events submitted before the
+        call may have been carried to the new sink instead of the old one, and the old sink was
+        left **open** rather than closed, because the drain thread may still be inside its
+        ``emit`` — the reasoning SPEC-027 FR-004 applies to an expired ``shutdown()``.
     """
 
     queued: int
@@ -79,6 +107,9 @@ class Health(NamedTuple):
     failed_batches: int
     stopped_reason: str | None = None
     sink: SinkLosses | None = None
+    retired: bool = False
+    submitted_after_shutdown: int = 0
+    incomplete_swaps: int = 0
 
 
 class _FlushMarker:
@@ -170,6 +201,8 @@ class Worker:
         self.dropped = 0
         self.failed_batches = 0
         self.stopped_reason: str | None = None
+        self.submitted_after_shutdown = 0
+        self.incomplete_swaps = 0
         self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
         self._stop = threading.Event()
         self._shutdown_done = False
@@ -221,6 +254,15 @@ class Worker:
         blocking write would let a wedged console stall the drain path. Lines may therefore
         interleave out of order under concurrency, but the counts they carry are exact.
 
+        A submission arriving after :meth:`shutdown` is still accepted, and counted where it
+        can be seen (SPEC-030 FR-001): the worker is retired and nothing will drain the queue,
+        so this is total silent loss until something reports it. The check is a single unlocked
+        read of a flag that is only ever set, never cleared, which is what keeps the normal path
+        free — taking the lock here would put every submission behind the counter's contention
+        for a condition that is false in every correct program. SPEC-019's objection to a
+        liveness check in ``submit`` does not reach it: that was about probing the thread, this
+        is a boolean already in the object's dict.
+
         Args:
           events: The span's buffered events, submitted as one item.
 
@@ -230,6 +272,8 @@ class Worker:
         Raises:
           None.
         """
+        if self._shutdown_done:
+            self._count_undeliverable()
         try:
             self._queue.put_nowait(events)
         except queue.Full:
@@ -239,13 +283,44 @@ class Worker:
             if total == 1 or total % _DROP_WARN_EVERY == 0:
                 _diag.lost("submission", total, "log queue full; count is cumulative")
 
+    def _count_undeliverable(self) -> None:
+        """Counts a post-shutdown submission and warns on the same throttle as overflow.
+
+        The two conditions warrant the same treatment for the same reason (FR-002): a caller
+        making this mistake makes it on every invocation, so a line per submission would be its
+        own outage, while total silence is how the mistake survives to production. The counter
+        moves before the line is attempted, per ``_diag``'s record-first rule, and the write
+        happens outside the lock so a wedged console cannot stall the drain path.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        with self._lock:
+            self.submitted_after_shutdown += 1
+            total = self.submitted_after_shutdown
+        if total == 1 or total % _DROP_WARN_EVERY == 0:
+            _diag.lost(
+                "submission",
+                total,
+                "logged after shutdown(), which is terminal; nothing will drain these. Use "
+                "flush() in a process that logs again. Count is cumulative",
+            )
+
     def health(self) -> Health:
         """Snapshots the delivery counters (SPEC-017 FR-005, SPEC-019 FR-003).
 
         This stays valid after :meth:`shutdown`: the counters are plain integers that outlive
         the thread, and the final drain consumes the queue, so ``queued`` reads 0 rather than a
         stale marker. The same applies to ``stopped_reason``, since a caller finding a dead
-        worker will usually call ``shutdown()`` next.
+        worker will usually call ``shutdown()`` next. Reading it after a shutdown is in fact
+        the point of ``retired`` and ``submitted_after_shutdown`` (SPEC-030 FR-001), which
+        report a state only a retired worker can be in.
 
         Args:
           None.
@@ -259,12 +334,18 @@ class Worker:
         with self._lock:
             dropped, failed_batches = self.dropped, self.failed_batches
             stopped_reason = self.stopped_reason
+            retired = self._shutdown_done
+            submitted_after_shutdown = self.submitted_after_shutdown
+            incomplete_swaps = self.incomplete_swaps
         return Health(
             queued=self._queue.qsize(),
             dropped=dropped,
             failed_batches=failed_batches,
             stopped_reason=stopped_reason,
             sink=self._sink_losses(),
+            retired=retired,
+            submitted_after_shutdown=submitted_after_shutdown,
+            incomplete_swaps=incomplete_swaps,
         )
 
     def _sink_losses(self) -> SinkLosses | None:
@@ -332,6 +413,137 @@ class Worker:
             return False
         return marker.delivered
 
+    def swap_sink(self, new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
+        """Retargets delivery at a new sink, draining and closing the previous one (FR-003).
+
+        This is what makes a late ``configure(sink=...)`` mean what it says. The sink was
+        captured once when the worker was built, so before SPEC-030 a later call updated the
+        config — which ``get_config().sink`` then reported — while every event continued to the
+        old sink: the config and the behaviour disagreed, and nothing said so.
+
+        The attribute is reassigned rather than the worker rebuilt, which keeps the queue, the
+        thread, the counters and the ``atexit`` registration intact; rebuilding would drop
+        whatever was queued and register a second drain. The order is the contract: drain first
+        so everything submitted before the call reaches the sink it was submitted for, swap,
+        then drain again before closing. That second drain is a fence rather than a delivery —
+        it proves the drain thread is not still inside the old sink's ``emit``, which is the one
+        way ``close()`` could be called under a writer.
+
+        On a drain that cannot be confirmed the swap still stands, because the caller asked for
+        the new sink and silently keeping the old one is the defect this method exists to fix.
+        What changes is that the old sink is left **open** and ``incomplete_swaps`` records it:
+        the drain thread may still be using it, and SPEC-027 FR-004 already settled that a
+        leaked resource beats a close raced against a write.
+
+        Both guards are re-taken after the first drain, which blocks and therefore cannot be
+        trusted to return into the state it left. Retirement is the one that bites: ``shutdown``
+        closes whatever ``self.sink`` was at that moment and latches its once-only flag, so a
+        swap reassigning afterwards would install a sink nothing will ever close, and then
+        report that the *old* one was left open when it had in fact just been closed.
+
+        ``configure()`` remains a startup call and this does not make it thread-safe. A span
+        finishing on another thread during the swap may land on either sink; what is guaranteed
+        is that everything submitted before the call was drained to the old one.
+
+        Args:
+          new_sink: The sink every subsequent batch is emitted to.
+          timeout: Seconds bounding both drains — one shared deadline, so a hung sink cannot
+            make ``configure()`` wait for twice the budget. It does **not** bound the closing of
+            the old sink, which has no timeout of its own; see :meth:`_close_swapped_out`.
+            ``None`` waits indefinitely.
+
+        Returns:
+          None. The outcome is reported through ``health().incomplete_swaps`` and one stderr
+          line rather than a return value, because the caller is ``configure()``, which has
+          never had one and whose callers do not check.
+
+        Raises:
+          None on a sink fault. A close that fails is announced, as everywhere else
+          (SPEC-025 FR-004).
+        """
+        with self._lock:
+            if self._shutdown_done or self.sink is new_sink:
+                return
+        deadline = None if timeout is None else time.monotonic() + timeout
+        drained = self.flush(timeout)
+        with self._lock:
+            if self._shutdown_done:
+                return
+            old = self.sink
+            if old is new_sink:
+                return
+            self.sink = new_sink
+        self._offer_stop_signal()
+        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+        if not (drained and self.flush(remaining)):
+            self._record_incomplete_swap(timeout)
+            return
+        self._close_swapped_out(old)
+
+    def _record_incomplete_swap(self, timeout: float | None) -> None:
+        """Counts a swap whose drain could not be confirmed, then announces it (FR-003).
+
+        Two things are reported at once because they have one cause: queued items may have been
+        carried to the new sink rather than the old one, and the old sink was left open. The
+        count is queued *items* — one per submitted span plus any marker — which makes it a
+        floor on the events involved, the useful direction for a reader deciding whether to care.
+
+        Args:
+          timeout: The budget the drain was given, rendered for the line.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        with self._lock:
+            self.incomplete_swaps += 1
+        _diag.lost(
+            "item",
+            self._queued_or_unknown(),
+            f"the previous sink could not be confirmed drained within "
+            f"{_bounded_seconds(timeout)} of a configure(sink=...); it is left open, and "
+            f"queued items may reach the new sink instead",
+        )
+
+    def _close_swapped_out(self, sink: Sink) -> None:
+        """Closes a sink the worker no longer delivers to, absorbing a failure.
+
+        This is reached only once both drains have been confirmed, so the *drain thread* is
+        provably out of this sink's ``emit``. An orphan-path emitter on an application thread
+        is not covered: it resolves the sink through ``_ensure_sink`` before emitting, so one
+        that read the old sink before ``configure()`` reassigned it can still be inside its
+        ``emit`` — which is why ``sinks/base.py`` requires ``close()`` to tolerate exactly that
+        (SPEC-028 FR-001), and why the sinks holding transport state take their lock in both.
+
+        The close is **not** bounded by the swap's timeout: ``Sink.close`` has no timeout of its
+        own, so bounding it needs an interruptible close — a change to the sink contract, not to
+        this method. Of :meth:`_close_if_owed`'s two reasons for rejecting a threaded close, only
+        the second reaches this site: the daemon killed mid-``commit()`` is an interpreter-exit
+        hazard and a swap runs in a live process, but an expired join still cannot tell a
+        slow-but-successful close from a stuck one, and would report a loss for a swap that
+        completed. A destination whose ``close()`` blocks therefore blocks ``configure()``,
+        recorded in ``architecture.md`` §13 rather than papered over.
+
+        It is deliberately not :meth:`_close_sink`, which answers a different question — that
+        one closes the sink the worker still holds, exactly once, and only after the thread has
+        ended.
+
+        Args:
+          sink: The sink that was swapped out.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        try:
+            sink.close()
+        except Exception as exc:
+            _diag.absorbed("closing a swapped-out sink", exc, "it may still hold its resources")
+
     def shutdown(self, timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
         """Stops the thread, drains and emits everything queued, then closes the sink.
 
@@ -348,6 +560,12 @@ class Worker:
         ``close()`` twice on a sink that may have partially released its resources; what
         SPEC-025 FR-004 changed is that the failure is announced rather than swallowed.
 
+        The worker does not come back, and :meth:`submit` keeps accepting afterwards — so a
+        caller that logs again queues events nothing will drain. That is reported rather than
+        prevented, through ``retired`` and ``submitted_after_shutdown`` (SPEC-030 FR-001) and
+        one stderr line; refusing the submission or restarting the thread were both rejected,
+        the second because a thread that resurrects itself fights a process trying to exit.
+
         Args:
           timeout: Seconds the join may take. ``None`` waits indefinitely, which is what this
             did unconditionally before and is still available on request.