log-foundry 0.10.2.dev28__tar.gz → 0.10.2.dev30__tar.gz

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev28
+Version: 0.10.2.dev30
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -254,10 +254,30 @@ drain thread may still be inside its `emit`, and `health().incomplete_swaps` rec
 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.
+The 5 s covers the **whole** call — both drains and the previous sink's `close()`. `Sink.close()`
+takes no timeout of its own (`KafkaSink.close()` flushes its producer, so an unreachable broker
+blocks it), so that close runs on its own daemon thread and is joined for whatever is left of the
+budget. A hung `close()` therefore costs you the budget, once, and the close carries on in the
+background afterwards.
+
+Nothing is *reported* when that join expires — a slow close is not a failed swap, and a counter
+that could not tell the two apart would be worse than none. What you get instead is a live
+reading: `health().closing_sinks` is how many swapped-out sinks are inside `close()` at the moment
+you ask. Non-zero once is a swap in progress; non-zero every time you look is a destination that
+is not coming back, still holding its resources.
+
+**What happens to that background close when the process exits.** `shutdown()` (which `atexit`
+runs for you) drains and closes the live sink first, then gives any still-running swapped-out close
+a short grace — 2 s, per `shutdown()` call, carved from that call's own timeout — to finish. A
+close that was merely slow completes. One that is genuinely stuck is abandoned there, and **its
+own buffered data is lost**: for a sink whose `close()` *is* its delivery, like
+`KafkaSink.close()` flushing the producer, that is everything it had not yet sent.
+`health().closing_sinks` is the only warning you get, which is why it is worth watching.
+
+The closer runs as a daemon thread deliberately. A non-daemon one is worse: CPython joins
+non-daemon threads **before** running `atexit`, so a single stuck `close()` would stop the exit
+drain from ever running — the live sink never drained, and your own `atexit` handlers never run
+either. The grace is what recovers the slow-close case that the daemon flag alone would lose.
 
 `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.
@@ -801,6 +821,9 @@ if (
     ...  # logs were silently lost — worth an alert
 ```
 
+`closing_sinks` is deliberately not a term here: it is briefly non-zero during a perfectly healthy
+sink swap, so a single reading is not a fault. Watch it over time instead — see the table below.
+
 They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
@@ -812,6 +835,7 @@ They tell you different things, and they want different responses:
 | `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. |
+| `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter, and the only field that falls as well as rises. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `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
@@ -839,8 +863,8 @@ means every log line since the shutdown has gone nowhere. That state used to rea
 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`) plus a sixth,
-seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
+(`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) 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.
 

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/README.md

@@ -218,10 +218,30 @@ drain thread may still be inside its `emit`, and `health().incomplete_swaps` rec
 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.
+The 5 s covers the **whole** call — both drains and the previous sink's `close()`. `Sink.close()`
+takes no timeout of its own (`KafkaSink.close()` flushes its producer, so an unreachable broker
+blocks it), so that close runs on its own daemon thread and is joined for whatever is left of the
+budget. A hung `close()` therefore costs you the budget, once, and the close carries on in the
+background afterwards.
+
+Nothing is *reported* when that join expires — a slow close is not a failed swap, and a counter
+that could not tell the two apart would be worse than none. What you get instead is a live
+reading: `health().closing_sinks` is how many swapped-out sinks are inside `close()` at the moment
+you ask. Non-zero once is a swap in progress; non-zero every time you look is a destination that
+is not coming back, still holding its resources.
+
+**What happens to that background close when the process exits.** `shutdown()` (which `atexit`
+runs for you) drains and closes the live sink first, then gives any still-running swapped-out close
+a short grace — 2 s, per `shutdown()` call, carved from that call's own timeout — to finish. A
+close that was merely slow completes. One that is genuinely stuck is abandoned there, and **its
+own buffered data is lost**: for a sink whose `close()` *is* its delivery, like
+`KafkaSink.close()` flushing the producer, that is everything it had not yet sent.
+`health().closing_sinks` is the only warning you get, which is why it is worth watching.
+
+The closer runs as a daemon thread deliberately. A non-daemon one is worse: CPython joins
+non-daemon threads **before** running `atexit`, so a single stuck `close()` would stop the exit
+drain from ever running — the live sink never drained, and your own `atexit` handlers never run
+either. The grace is what recovers the slow-close case that the daemon flag alone would lose.
 
 `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.
@@ -765,6 +785,9 @@ if (
     ...  # logs were silently lost — worth an alert
 ```
 
+`closing_sinks` is deliberately not a term here: it is briefly non-zero during a perfectly healthy
+sink swap, so a single reading is not a fault. Watch it over time instead — see the table below.
+
 They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
@@ -776,6 +799,7 @@ They tell you different things, and they want different responses:
 | `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. |
+| `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter, and the only field that falls as well as rises. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `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
@@ -803,8 +827,8 @@ means every log line since the shutdown has gone nowhere. That state used to rea
 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`) plus a sixth,
-seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
+(`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) 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.
 

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/pyproject.toml

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

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/__init__.py

@@ -70,6 +70,9 @@ def health() -> Health:
 
     ``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.
+    ``closing_sinks`` is deliberately absent for the same kind of reason: it is briefly non-zero
+    during a perfectly healthy sink swap, so alerting on a single reading would fire on correct
+    use. It is a gauge to watch over time, not a term in this test.
 
     Args:
       None.
@@ -81,8 +84,11 @@ def health() -> Health:
       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
+      previous sink could not be confirmed, leaving that sink open. ``closing_sinks`` is the
+      odd one out — a live gauge rather than a counter, reporting how many swapped-out sinks
+      are inside ``close()`` right now, so a destination stuck there is visible at all; it
+      falls back to zero on its own, and only a *persistently* non-zero reading is a fault.
+      ``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
@@ -117,7 +123,9 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     (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``
+      timeout: Seconds bounding the wait for the background thread and, carved from the same
+        budget, a short grace for any sink still closing after a late ``configure(sink=...)``
+        (SPEC-027 FR-004, SPEC-030 FR-003). ``None``
         waits indefinitely, which is what this did unconditionally before and is still
         available on request, but is unsafe anywhere with an execution deadline — ``atexit`` is
         one such place, where a sink blocked in a network call would hold the process open. An

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/api.py

@@ -30,6 +30,12 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
     the sink resolved through ``_ensure_sink`` so a zero-config orphan log falls back to
     ``StdoutSink`` rather than crashing.
 
+    That direct handoff is **settled, not pending**: SPEC-004's worker took over the traced
+    path and this branch was deliberately left synchronous, so a level call outside a span is
+    never silently dropped for want of a worker (``architecture.md`` §12 Resolved, "Orphan
+    logs"). It carried a comment saying the worker "will later" own it long after the
+    decision was made (SPEC-031 FR-003).
+
     The orphan branch is the one that reaches the sink on the caller's own thread, with no
     worker between them to absorb a failure, so the whole branch is guarded (SPEC-025
     FR-003) — ``_ensure_sink`` constructs the sink on first use, so a sink that fails to

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/config.py

@@ -86,10 +86,11 @@ def configure(
     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.
+    The bound covers the whole call, the close included. ``Sink.close`` takes no timeout, so that
+    close runs on its own daemon thread and is joined for what is left of the budget: a
+    destination that hangs in ``close()`` delays this call by the budget and no more, then carries
+    on in the background. An expired join reports nothing, since a slow close and a stuck one
+    cannot be told apart at that moment; ``health().closing_sinks`` reports the live fact instead.
 
     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.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/console.py

@@ -16,13 +16,24 @@ class ConsoleWriter:
     operator sees it without waiting for the async flush. It is deliberately dumb, rendering
     an already-built event dict and knowing nothing about spans, and echo is additive — an
     echoed event still rides the normal pipeline to the sink.
+
+    The default stream is **stderr**, not stdout (SPEC-031 FR-003, which corrected two
+    documents that said otherwise). It is the twelve-factor convention ``StderrSink`` already
+    cites — logs on stderr, the application's own output on stdout — so an echo cannot corrupt
+    a program whose stdout is a data stream someone pipes.
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the writer to an output stream.
+        """Binds the writer to an output stream, once, at construction.
+
+        The binding is deliberate and permanent for the life of the writer: a later
+        ``contextlib.redirect_stderr`` or a test's capture of ``sys.stderr`` is not honoured,
+        because the attribute was resolved here. ``api._console`` is built at import, so in
+        practice a process's echo stream is fixed before any test runs. Passing ``stream=``
+        explicitly is how a caller — a test above all — captures the output (SPEC-031 FR-003).
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stderr``.
+          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now.
 
         Returns:
           None.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/decorator.py

@@ -243,7 +243,8 @@ def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) ->
 
     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.
+      timeout: Seconds bounding the whole swap — both drains and the close of the previous
+        sink share it as one deadline.
 
     Returns:
       None.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/model.py

@@ -8,6 +8,8 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from log_foundry.config import get_config
+from log_foundry.ids import new_log_id
 from log_foundry.sanitize import sanitize_fields, truncate_str, truncate_tail
 
 if TYPE_CHECKING:
@@ -72,6 +74,12 @@ def build_event(
     bounded too, since both are caller-supplied text and leaving either out would keep
     ``info(huge_string)`` unbounded.
 
+    ``get_config`` and ``new_log_id`` are imported at module scope (SPEC-031 FR-004). They were
+    function-local to avoid a cycle, but there is none to avoid: neither ``config`` nor ``ids``
+    imports this module, and ``config``'s own back-references to ``decorator`` stay local for
+    the reason its docstrings give. This is the hottest path in the library, so resolving them
+    once at import is what ``sanitize`` already does with its one-time bindings.
+
     Args:
       span: The span the event belongs to, supplying identity and defaults.
       level: The severity label, such as ``"INFO"``.
@@ -85,9 +93,6 @@ def build_event(
     Raises:
       None.
     """
-    from log_foundry.config import get_config
-    from log_foundry.ids import new_log_id
-
     cfg = get_config()
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
     safe, clipped = sanitize_fields(merged, cfg=cfg)
@@ -226,8 +231,6 @@ def end_event(
     Raises:
       None.
     """
-    from log_foundry.config import get_config
-
     level = "INFO" if status == "ok" else "ERROR"
     event = build_event(span, level, _END_MESSAGE, fields={}, baggage={})
     event["duration_ms"] = (time.monotonic() - span.start_ts) * 1000.0
@@ -266,8 +269,6 @@ def backfill_baggage(span: Span, baggage: dict[str, object]) -> None:
     """
     if not baggage:
         return
-    from log_foundry.config import get_config
-
     safe, clipped = sanitize_fields(baggage, cfg=get_config())
     for event in span.events:
         if event.get("message") in (_START_MESSAGE, _END_MESSAGE):

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sanitize.py

@@ -142,7 +142,7 @@ class _Coercer:
     ``build_event`` already allocates per event, it is noise.
     """
 
-    __slots__ = ("_cfg", "_parents", "truncated")
+    __slots__ = ("_cfg", "_int_ceiling", "_parents", "truncated")
 
     def __init__(self, cfg: Config) -> None:
         """Starts a pass with the configured ceilings and an empty ancestor chain.
@@ -152,6 +152,11 @@ class _Coercer:
         recursion for the whole descent, so its ``id()`` cannot be recycled underneath us, and
         two siblings referencing the same object are not a cycle and must both render.
 
+        The integer ceiling is resolved here, once per pass rather than once per integer
+        (SPEC-031 FR-004): it reads ``sys.get_int_max_str_digits()``, which cannot change
+        during a coercion pass, and the alternative sat four lines below an ``int.__lt__``
+        binding justified by this being a per-value hot path.
+
         Args:
           cfg: The config supplying ``max_value_bytes``, ``max_keys`` and ``max_depth``.
 
@@ -162,6 +167,7 @@ class _Coercer:
           None.
         """
         self._cfg = cfg
+        self._int_ceiling = _int_digit_ceiling(cfg.max_value_bytes)
         self.truncated = False
         self._parents: list[int] = []
 
@@ -368,7 +374,7 @@ class _Coercer:
         """
         digits = value.bit_length() * _LOG10_2_NUM // _LOG10_2_DEN + 1
         rendered = digits + 1 if _INT_LT(value, 0) else digits
-        if rendered <= _int_digit_ceiling(self._cfg.max_value_bytes):
+        if rendered <= self._int_ceiling:
             return value
         self.truncated = True
         return f"<int: ~{digits} digits>"

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/_socket.py

@@ -33,21 +33,45 @@ def _make_tcp(host: str, port: int, timeout: float) -> socket.socket:
     return socket.create_connection((host, port), timeout=timeout)
 
 
-def _make_udp() -> socket.socket:
-    """Opens an unconnected UDP socket.
+def _make_udp(host: str) -> socket.socket:
+    """Opens an unconnected UDP socket in an address family the host resolves to (SPEC-031).
+
+    The family is resolved rather than assumed: a hardcoded ``AF_INET`` made every ``sendto``
+    to an IPv6 destination fail, silently, until the retry bound abandoned the message. TCP
+    never had the defect because ``socket.create_connection`` resolves for itself.
+
+    **IPv4 wins when the host offers it**, and taking the first result instead was measured
+    losing logs. ``getaddrinfo`` sorts by RFC 6724, which puts AAAA first, so a dual-stack
+    name like ``localhost`` would move from IPv4 — where every deployment of this library has
+    sent — to IPv6, and a collector bound to ``0.0.0.0:514`` would never see the datagram. UDP
+    is unconnected, so that failure is *silent*: ``sendto`` succeeds locally, ``emit`` returns,
+    and no counter moves. FR-002 AC-2 requires delivery to a hostname to be unchanged, and
+    this is what makes it so while AC-1 still holds. It is a fixed preference, not
+    happy-eyeballs, address caching, or a setting — none of which this FR builds.
 
     This is a module-level seam so tests can substitute a fake socket without network access.
 
     Args:
-      None.
+      host: The destination host, resolved to choose the family.
 
     Returns:
       The socket.
 
     Raises:
-      OSError: If the socket cannot be created.
+      OSError: If the host resolves to nothing, or the socket cannot be created. Both reach
+        ``_send_one``'s handler, which counts and announces rather than raising — a
+        ``gaierror`` is an ``OSError``, so an unresolvable host fails exactly as an
+        unreachable one already did. The empty-result case is raised as one explicitly: CPython
+        raises rather than returning ``[]``, but indexing it would produce an ``IndexError``,
+        which is *not* an ``OSError`` and would escape that handler into the caller — the one
+        thing SPEC-025 says this library may never do.
     """
-    return socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    families = [entry[0] for entry in socket.getaddrinfo(host, None, type=socket.SOCK_DGRAM)]
+    if not families:
+        raise socket.gaierror(socket.EAI_NONAME, "resolution returned no address family")
+    return socket.socket(
+        socket.AF_INET if socket.AF_INET in families else families[0], socket.SOCK_DGRAM
+    )
 
 
 class SocketTransport:
@@ -235,6 +259,10 @@ class SocketTransport:
     def _socket(self) -> socket.socket:
         """Returns the held socket, opening one if none is held.
 
+        The UDP address family is resolved here rather than per message, because this is the
+        only place a socket is created and the socket outlives every send made through it
+        (SPEC-031 FR-002).
+
         Args:
           None.
 
@@ -242,11 +270,11 @@ class SocketTransport:
           The socket.
 
         Raises:
-          OSError: If the socket cannot be created or connected.
+          OSError: If the socket cannot be created, resolved or connected.
         """
         if self._sock is None:
             self._sock = (
-                _make_udp() if self._transport == "udp" else _make_tcp(
+                _make_udp(self._host) if self._transport == "udp" else _make_tcp(
                     self._host, self._port, self._timeout
                 )
             )

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/file.py

@@ -113,12 +113,16 @@ class RotatingFileSink:
     Two independent triggers may be enabled, either or both. With a positive ``max_bytes`` it
     rotates before the write that would push the active file past that size, so the file never
     grows unbounded; with a ``when`` unit code and an interval it rotates on the first emit after
-    that period has elapsed since the last rotation.
+    that period has elapsed since the last rotation. That period is measured on the monotonic
+    clock (SPEC-031 FR-001), so a wall-clock step in either direction neither defers a rotation
+    nor forces an early one.
 
     Rotation renames the active file through numbered backups, prunes any beyond the backup
     count, and opens a fresh active file — a backup count of zero keeps none, simply replacing
-    the active file. No event is lost across a rotation, because the rotate happens before the
-    pending event is written and the event lands in the fresh file.
+    the active file. Backups are numbered rather than timestamped, so no filename derives from
+    a clock at all and the monotonic deadline has no naming consequence. No event is lost across
+    a rotation, because the rotate happens before the pending event is written and the event
+    lands in the fresh file.
 
     A rotation rebinds the active stream, so it is the sink where concurrent writers did real
     damage: a second thread mid-``emit`` could write to the handle rotation had just closed, or
@@ -249,24 +253,34 @@ class RotatingFileSink:
         return unit * interval
 
     def _schedule_next(self) -> float | None:
-        """Returns the wall-clock time of the next time-based rotation.
+        """Returns the monotonic-clock deadline for the next time-based rotation (SPEC-031).
+
+        Monotonic rather than wall-clock for the reason ``Span.start_ts`` is: a backward step —
+        an NTP correction, a container clock sync — larger than the interval would otherwise
+        defer every time-based rotation until wall-clock caught up, silently defeating this
+        class's promise to bound on-disk growth. Nothing here is a timestamp anyone reads; it is
+        only ever compared against another reading of the same clock.
 
         Args:
           None.
 
         Returns:
-          The absolute time, or ``None`` when there is no time trigger.
+          The deadline as a ``time.monotonic()`` reading, or ``None`` when there is no time
+          trigger.
 
         Raises:
           None.
         """
         if self._interval_seconds is None:
             return None
-        return time.time() + self._interval_seconds
+        return time.monotonic() + self._interval_seconds
 
     def _should_rotate(self, incoming: int) -> bool:
         """Decides whether to rotate before writing the next event.
 
+        The time trigger reads ``time.monotonic()``, the same clock :meth:`_schedule_next`
+        wrote the deadline on; comparing the two clocks is what the SPEC-031 fix removes.
+
         Args:
           incoming: The byte cost of the event about to be written.
 
@@ -282,7 +296,7 @@ class RotatingFileSink:
             and self._size + incoming > self._max_bytes
         ):
             return True
-        return self._next_rollover is not None and time.time() >= self._next_rollover
+        return self._next_rollover is not None and time.monotonic() >= self._next_rollover
 
     def _rotate(self) -> None:
         """Closes the active file, shifts and prunes backups, then opens a fresh active file.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/logstash.py

@@ -24,6 +24,18 @@ class LogstashSink:
     :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.
 
+    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.
+
+    **A hostname that resolves to both families goes to IPv4**, because that is where every
+    release before this one sent and moving it silently would strand a collector bound to
+    ``0.0.0.0``. The consequence is the mirror case, stated because nothing else states it: a
+    dual-stack *name* whose collector listens on IPv6 only will not be reached over UDP, and
+    since UDP is unconnected that failure is silent — no exception, no counter. Give the IPv6
+    literal, or a name with no ``A`` record, to select IPv6 for such a destination. TCP is
+    unaffected either way; ``create_connection`` tries each candidate in turn.
+
     It takes **no** transport lock (SPEC-028 FR-002) of its own: whichever backend it built owns
     that decision — ``SocketTransport`` locks its sends, ``HTTPSink`` holds no transport to
     guard. The post-close rule follows the same split (SPEC-032 FR-004), and the two modes

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/stdout.py

@@ -29,10 +29,15 @@ class StdoutSink:
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the sink to an output stream.
+        """Binds the sink to an output stream, once, at construction.
+
+        The binding is deliberate and permanent for the life of the sink: a later
+        ``contextlib.redirect_stdout`` or a test's capture of ``sys.stdout`` is not honoured,
+        because the attribute was resolved here. Passing ``stream=`` explicitly is how a caller
+        — a test above all — captures the output (SPEC-031 FR-003).
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stdout``.
+          stream: The stream to write to, defaulting to ``sys.stdout`` as resolved now.
 
         Returns:
           None.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/syslog.py

@@ -34,6 +34,18 @@ class SyslogSink:
     and a severity mapped from the event's level. UDP sends one datagram per event, TCP uses
     octet-counted framing (RFC 6587), and the whole sink is dependency-free.
 
+    Both IPv4 and IPv6 destinations are supported, on 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.
+
+    **A hostname that resolves to both families goes to IPv4**, because that is where every
+    release before this one sent and moving it silently would strand a collector bound to
+    ``0.0.0.0``. The consequence is the mirror case, stated because nothing else states it: a
+    dual-stack *name* whose collector listens on IPv6 only will not be reached over UDP, and
+    since UDP is unconnected that failure is silent — no exception, no counter. Give the IPv6
+    literal, or a name with no ``A`` record, to select IPv6 for such a destination. TCP is
+    unaffected either way; ``create_connection`` tries each candidate in turn.
+
     It takes **no** transport lock (SPEC-028 FR-002) of its own: the socket it holds is a
     :class:`~log_foundry.sinks._socket.SocketTransport`, which locks its own sends. Its
     post-close refusal comes from there too (SPEC-032 FR-004) — a batch emitted after

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/util.py

@@ -20,11 +20,16 @@ class StderrSink(StdoutSink):
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the sink to an output stream.
+        """Binds the sink to an output stream, once, at construction.
+
+        The binding is resolved here and not re-read per write, so a later
+        ``contextlib.redirect_stderr`` is not honoured — the same property
+        :class:`~log_foundry.sinks.stdout.StdoutSink` documents (SPEC-031 FR-003), restated
+        because this override means none of that docstring is inherited.
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stderr``. An explicit one, such
-            as a ``StringIO``, can be injected for capture.
+          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now. An
+            explicit one, such as a ``StringIO``, can be injected for capture.
 
         Returns:
           None.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev30}/src/log_foundry/worker.py

@@ -26,6 +26,15 @@ and an unbounded join there is a hung process.
 
 _DROP_WARN_EVERY = 1000
 
+DEFAULT_CLOSER_GRACE = 2.0
+"""Seconds :meth:`Worker.shutdown` gives an outstanding swapped-out close to finish.
+
+Deliberately much smaller than the shutdown budget it is carved from. This is a last chance for
+a close that is *nearly* done, not a second full attempt: it already had the swap's whole budget
+(``DEFAULT_SWAP_TIMEOUT``) before ``shutdown`` was ever called, so one still running here is far
+more likely stuck than slow, and every second spent on it is a second the process does not exit.
+"""
+
 DEFAULT_SWAP_TIMEOUT = 5.0
 """Seconds a late ``configure(sink=...)`` will spend draining the previous sink (FR-003).
 
@@ -100,6 +109,14 @@ class Health(NamedTuple):
         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()``.
+      closing_sinks: Swapped-out sinks whose ``close()`` is running *at this instant* — a live
+        gauge, not a counter, and the only field here that can fall as well as rise. A close is
+        bounded only in how long ``configure()`` waits for it, so this is how a destination
+        stuck in ``close()`` becomes visible at all. Reading it non-zero once means a swap just
+        happened; reading it non-zero repeatedly means a close is not coming back, and that sink
+        still holds its resources. It is deliberately a live read rather than a count of expired
+        joins: a slow close and a stuck one are indistinguishable at the moment a join expires,
+        and SPEC-028 reverted a design that guessed.
     """
 
     queued: int
@@ -110,6 +127,7 @@ class Health(NamedTuple):
     retired: bool = False
     submitted_after_shutdown: int = 0
     incomplete_swaps: int = 0
+    closing_sinks: int = 0
 
 
 class _FlushMarker:
@@ -203,6 +221,7 @@ class Worker:
         self.stopped_reason: str | None = None
         self.submitted_after_shutdown = 0
         self.incomplete_swaps = 0
+        self._closers: list[threading.Thread] = []
         self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
         self._stop = threading.Event()
         self._shutdown_done = False
@@ -337,6 +356,8 @@ class Worker:
             retired = self._shutdown_done
             submitted_after_shutdown = self.submitted_after_shutdown
             incomplete_swaps = self.incomplete_swaps
+            self._closers = [closer for closer in self._closers if closer.is_alive()]
+            closing_sinks = len(self._closers)
         return Health(
             queued=self._queue.qsize(),
             dropped=dropped,
@@ -346,6 +367,7 @@ class Worker:
             retired=retired,
             submitted_after_shutdown=submitted_after_shutdown,
             incomplete_swaps=incomplete_swaps,
+            closing_sinks=closing_sinks,
         )
 
     def _sink_losses(self) -> SinkLosses | None:
@@ -447,10 +469,9 @@ class Worker:
 
         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.
+          timeout: Seconds bounding the **whole** call — one deadline shared by both drains and
+            the close of the old sink, so a destination that hangs in any of the three cannot
+            hold ``configure()`` for a multiple of the budget. ``None`` waits indefinitely.
 
         Returns:
           None. The outcome is reported through ``health().incomplete_swaps`` and one stderr
@@ -478,7 +499,8 @@ class Worker:
         if not (drained and self.flush(remaining)):
             self._record_incomplete_swap(timeout)
             return
-        self._close_swapped_out(old)
+        left = None if deadline is None else max(0.0, deadline - time.monotonic())
+        self._close_swapped_out(old, left)
 
     def _record_incomplete_swap(self, timeout: float | None) -> None:
         """Counts a swap whose drain could not be confirmed, then announces it (FR-003).
@@ -507,8 +529,8 @@ class Worker:
             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.
+    def _close_swapped_out(self, sink: Sink, timeout: float | None) -> None:
+        """Closes a sink the worker no longer delivers to, waiting only for the budget.
 
         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
@@ -517,14 +539,24 @@ class Worker:
         ``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.
+        ``Sink.close`` takes no timeout, so the close is run on its own thread and joined for
+        what is left of the swap's budget. **An expired join decides only who waits** — it moves
+        no counter and writes no line, which is what dissolves SPEC-028's objection that an
+        expired join cannot tell a slow-but-successful close from a stuck one and so reports a
+        loss for closes that completed. What *is* observable is a live fact rather than an
+        inference: ``health().closing_sinks`` counts the closes running at the moment it is read.
+
+        The thread is a **daemon**, and it is :meth:`_join_closers` that makes that safe rather
+        than merely available. A non-daemon thread was tried and is worse on its own: CPython
+        joins non-daemon threads *before* running ``atexit``, so one hung close stops the exit
+        drain from ever running and loses everything buffered in the **live** sink, along with
+        the application's own exit handlers. A daemon alone is also worse on its own, in the
+        opposite case: a close that is slow but *succeeding* is killed at exit, losing whatever
+        it was flushing. ``shutdown`` therefore drains and closes the live sink first, then
+        joins any outstanding closer for what is left of its budget — so a slow close finishes,
+        a hung one costs only the grace, and neither can reach the live sink. What SPEC-028
+        refused to abandon was the sink the worker was *still delivering to*; this one has been
+        fenced out of the delivery path by two confirmed drains.
 
         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
@@ -532,6 +564,49 @@ class Worker:
 
         Args:
           sink: The sink that was swapped out.
+          timeout: Seconds to wait for the close before returning and letting it finish on its
+            own. ``None`` waits indefinitely.
+
+        Returns:
+          None.
+
+        Raises:
+          None. ``Thread.start`` raises when the platform will not give the process another
+            thread, and a swap that cannot spawn one must leave the sink open and say so rather
+            than fall back to an inline close — the fallback would reintroduce the unbounded
+            wait this method exists to remove, in the one situation where the process is
+            already under resource pressure.
+        """
+        closer = threading.Thread(
+            target=self._close_detached,
+            args=(sink,),
+            name="log-foundry-sink-close",
+            daemon=True,
+        )
+        try:
+            closer.start()
+        except Exception as exc:
+            _diag.absorbed(
+                "starting the thread that closes a swapped-out sink",
+                exc,
+                "it is left open and may still hold its resources",
+            )
+            return
+        with self._lock:
+            self._closers = [old for old in self._closers if old.is_alive()]
+            self._closers.append(closer)
+        closer.join(timeout)
+
+    def _close_detached(self, sink: Sink) -> None:
+        """Closes a swapped-out sink on its own thread, absorbing a failure.
+
+        The guard is what makes the thread safe to leave unattended: an exception escaping here
+        would reach CPython's thread bootstrap, which prints a full traceback carrying the
+        exception's message — the user data arch §6 keeps out of anything the library says about
+        itself, and the reason :meth:`shutdown` guards its own close.
+
+        Args:
+          sink: The sink to close.
 
         Returns:
           None.
@@ -578,11 +653,13 @@ class Worker:
             a full traceback carrying the exception's message, which arch §6 keeps out of
             anything the library says about itself.
         """
+        deadline = None if timeout is None else time.monotonic() + timeout
         with self._lock:
             first = not self._shutdown_done
             self._shutdown_done = True
         if not first:
             self._close_if_owed()
+            self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
             return
         self._stop.set()
         try:
@@ -603,6 +680,56 @@ class Worker:
             )
             return
         self._close_if_owed()
+        self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
+
+    def _join_closers(self, timeout: float | None) -> None:
+        """Gives a swapped-out sink's close its last chance before the process exits.
+
+        This is what makes the daemon closer of :meth:`_close_swapped_out` safe rather than
+        merely available. A daemon is killed wherever it has reached at interpreter exit, so
+        without this a close that was slow but *succeeding* — a ``KafkaSink`` flushing its
+        producer, where the close is the delivery — would lose its buffer, which a non-daemon
+        thread would not have. Measured both ways: daemon alone lost those events, non-daemon
+        alone lost everything in the *live* sink instead, and this join is what takes neither
+        loss.
+
+        **The cap is the mechanism.** The wait is the smaller of ``DEFAULT_CLOSER_GRACE`` and
+        what remains of ``shutdown``'s own budget: capped so a stuck close cannot hold a process
+        at exit for the whole shutdown budget, and carved from that budget so it cannot extend it
+        either. Running after :meth:`_close_if_owed` rather than before it is defence in depth
+        rather than the guarantee — measured, the two orders deliver the live sink identically,
+        because the cap returns control long before anything is at risk. It is still the right
+        order, and pinned by a test: it is what holds if an external deadline kills the process
+        *during* the grace, where the live sink would otherwise be the one left unclosed.
+
+        It runs on the idempotent path too. A first ``shutdown`` that expired on a wedged drain
+        thread returns before ever reaching here, and the ``atexit`` call that follows would
+        otherwise return instantly — denying the grace to a swapped-out close that is healthy and
+        moments from finishing, which is exactly the loss the grace exists to prevent. The closer
+        is independent of the worker thread, so a wedged worker is no reason to abandon it. The
+        expired path itself still skips it, and that costs nothing: the thread join consumed the
+        budget, so the remainder is zero.
+
+        Args:
+          timeout: Seconds remaining in ``shutdown``'s budget, further capped by
+            ``DEFAULT_CLOSER_GRACE`` and shared across every outstanding close. ``None`` takes
+            the cap rather than waiting indefinitely — an unbounded ``shutdown`` is a caller's
+            choice about draining events, not a licence for a stuck close to hold the exit.
+
+        Returns:
+          None.
+
+        Raises:
+          None. A join on a thread that has already finished is a no-op, and one that has not
+            is abandoned at the deadline — which is the daemon's contract, not a failure.
+        """
+        with self._lock:
+            closers = [closer for closer in self._closers if closer.is_alive()]
+            self._closers = closers
+        grace = DEFAULT_CLOSER_GRACE if timeout is None else min(timeout, DEFAULT_CLOSER_GRACE)
+        deadline = time.monotonic() + grace
+        for closer in closers:
+            closer.join(max(0.0, deadline - time.monotonic()))
 
     def _close_if_owed(self) -> None:
         """Closes the sink exactly once, and only once the drain thread has ended.
@@ -727,6 +854,12 @@ class Worker:
         this sweep, and that one waits out its timeout — then returns False, which is correct
         either way.
 
+        The reliance on ``queue.Queue``'s private ``mutex`` and ``queue`` is deliberate and is
+        recorded in ``architecture.md`` §13 Known Constraints (SPEC-031 FR-005): there is no
+        public "inspect without consuming", and the draining alternative would destroy the
+        evidence the terminal-failure line reports. A CPython change would surface as the test
+        that exercises this against a mixed queue, rather than as waiters silently timing out.
+
         Args:
           None.