log-foundry 0.10.2.dev29__tar.gz → 0.10.2.dev31__tar.gz

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev29
+Version: 0.10.2.dev31
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -862,6 +862,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 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.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 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 four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/README.md

@@ -826,6 +826,15 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 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.
 
+`retired` is also the one field reported for a process that has **no worker at all**. A program
+that only ever calls `info()`/`error()` outside a span emits synchronously and builds no background
+worker, so every other field describes something that does not exist and reads zero. Its
+`shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
+`True` afterwards rather than staying vacuously `False`. `submitted_after_shutdown` stays `0` there
+by design: a later level call is *refused* at the closed sink and announced on stderr — if the sink
+guards its own post-close state — rather than queued where nothing will drain it, and those are not
+the same claim. A stateless sink such as the default `StdoutSink` still accepts it.
+
 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 four more
 (`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/pyproject.toml

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

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/src/log_foundry/__init__.py

@@ -98,7 +98,9 @@ def health() -> Health:
       ``failed`` is an upper bound on loss rather than a count of it, since a sink that raises
       on total failure counts the attempt and hands the batch back for the worker to retry. A
       process that has never logged has no worker, and asking does not create one — the
-      snapshot is simply zeroed. Valid after :func:`shutdown`.
+      snapshot is simply zeroed, except for ``retired``, which stays truthful even for a
+      process that only ever logged outside a span and so built no worker at all (SPEC-031
+      FR-006). Valid after :func:`shutdown`.
 
     Raises:
       None.
@@ -122,6 +124,15 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     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.
 
+    A process that only ever logged **outside** a span built no worker, and this used to be a
+    no-op there, leaving the sink open forever: every event lost on a sink whose ``close()`` is
+    what delivers them, the flush and the resource on a synchronous one. It now closes that
+    sink — exactly once, and without creating a worker to do it — and ``health().retired``
+    reads ``True`` afterwards rather than staying vacuously ``False`` (SPEC-031 FR-006). A
+    later level call reaches a closed sink, so a sink that guards its own post-close state
+    refuses it and one stderr line is written; a stateless one such as ``StdoutSink`` still
+    accepts it (SPEC-032).
+
     Args:
       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=...)``

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/src/log_foundry/api.py

@@ -6,6 +6,7 @@ from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
 from log_foundry.context import set_baggage
+from log_foundry.decorator import _note_orphan_emit
 from log_foundry.ids import new_span_id, new_trace_id
 from log_foundry.model import Span, build_event
 
@@ -30,6 +31,27 @@ 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).
+
+    Because no worker is built here, nothing else in the library knows the sink was ever
+    written to — so this branch records it (SPEC-031 FR-006). That is what arms the exit-time
+    close for a process which only ever logs this way, and keying it on a sink this call is
+    about to write to, rather than on a *configured* sink, is deliberate: ``configure()``
+    materializes a ``StdoutSink`` whether or not anything is logged through it, and closing one
+    nothing was ever written to is cost with no benefit.
+
+    It is armed **before** the emit rather than after it, which matters for the sinks most
+    likely to need the close. SPEC-026 FR-001 makes a total failure raise, so an orphan-only
+    process against a dead syslog or HTTP destination raises on every call — and arming
+    afterwards would leave the socket that failure came from open forever, which is the leak
+    this FR exists to stop, in exactly the case that is leaking. A sink that raised is still a
+    sink that was written to. ``_ensure_sink`` is resolved first, so a sink that fails to
+    *construct* arms nothing: there is nothing to close.
+
     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
@@ -66,7 +88,9 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
                 start_ts=0.0,
             )
             event = build_event(orphan, level, message, fields=fields, baggage=baggage)
-            _ensure_sink().emit([event])
+            sink = _ensure_sink()
+            _note_orphan_emit()
+            sink.emit([event])
         except Exception as exc:
             _diag.absorbed("emitting an orphan log", exc, "the event was lost")
     if echo and event is not None:

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev31}/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.dev29 → log_foundry-0.10.2.dev31}/src/log_foundry/decorator.py

@@ -32,6 +32,9 @@ __all__ = ["continue_trace", "trace"]
 _worker: Worker | None = None
 _worker_lock = threading.Lock()
 _atexit_registered = False
+_orphan_close_owed = False
+_orphan_sink_closed = False
+_orphan_retired = False
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -202,23 +205,127 @@ def _get_worker() -> Worker:
     Raises:
       Exception: Whatever constructing the sink or worker raises.
     """
-    global _worker, _atexit_registered
+    global _worker
     if _worker is None:
         with _worker_lock:
             if _worker is None:
-                if not _atexit_registered:
-                    atexit.register(_shutdown_worker)
-                    _atexit_registered = True
+                _register_exit_handler()
                 _worker = Worker(_ensure_sink())
     return _worker
 
 
+def _register_exit_handler() -> None:
+    """Registers the one ``atexit`` handler that covers both delivery paths (SPEC-031 FR-006).
+
+    One registration, not two, and one flag guarding it. :func:`_shutdown_worker` handles the
+    worker path *and* the orphan path, so an orphan log arming this does not cost a later
+    ``@trace`` its exit drain — which reusing a worker-only registration flag would. Two
+    handlers would be worse still: ``atexit`` runs LIFO, so the second would close a sink the
+    first had already closed. What is made once-only is the *close*, not the registration.
+
+    Callers hold ``_worker_lock``.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _atexit_registered
+    if not _atexit_registered:
+        atexit.register(_shutdown_worker)
+        _atexit_registered = True
+
+
+def _note_orphan_emit() -> None:
+    """Records that a level call with no span reached the sink (SPEC-031 FR-006).
+
+    This is what arms the exit-time close, and it is deliberately keyed on an event having
+    *landed* rather than on a sink existing: ``configure()`` runs ``_ensure_sink()``
+    unconditionally, so a bare ``configure(service=…)`` has already built a ``StdoutSink``,
+    and keying on that would close a sink nothing was ever written to.
+
+    The unlocked read is the fast path on a per-call route — the flag is written once and
+    never cleared, so a racing reader either sees it set or takes the lock and finds it set
+    there.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _orphan_close_owed
+    if _orphan_close_owed:
+        return
+    with _worker_lock:
+        if not _orphan_close_owed:
+            _register_exit_handler()
+            _orphan_close_owed = True
+
+
+def _close_orphan_sink() -> None:
+    """Closes a sink only the orphan path ever wrote to, once (SPEC-031 FR-006).
+
+    A process that never opens a span builds no worker, so nothing owned the sink's close and
+    nothing performed it: on a locally-buffering sink every event died in the client's batch,
+    on a synchronous one the flush and the resource were lost, and ``health()`` read all-clear
+    because every field it carries describes a worker that does not exist.
+
+    A live worker owns the close instead, and this returns — that is what makes a mixed
+    process exactly one ``close()`` in either order. It also inherits the worker's reasons for
+    *not* closing: an expired :meth:`Worker.shutdown` leaves the sink open because the drain
+    thread may still be inside ``emit``.
+
+    That check is read **under** ``_worker_lock``, not ahead of it, because :func:`_get_worker`
+    assigns ``_worker`` while holding that same lock. Unlocked, a ``shutdown()`` racing a first
+    ``@trace`` could read ``None``, block behind the worker's construction, and then close the
+    sink underneath the worker that had just captured it — reproduced with an injected
+    preemption point, the way SPEC-028 demonstrates the races that need one.
+
+    The once-only flag is set ahead of the close, as ``Worker.shutdown``'s is: a second
+    ``close()`` on a sink that partially released its resources is worse than an unclosed one.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None. This runs from ``atexit``, where an escaping exception makes CPython print a
+        traceback carrying the message arch §6 keeps out of anything the library says about
+        itself. ``Exception``, never ``BaseException`` (SPEC-025 FR-004).
+    """
+    global _orphan_sink_closed
+    with _worker_lock:
+        if _worker is not None or not _orphan_close_owed or _orphan_sink_closed:
+            return
+        _orphan_sink_closed = True
+    try:
+        _ensure_sink().close()
+    except Exception as exc:
+        _diag.absorbed("closing the sink", exc, "it may still hold its resources")
+
+
 def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
-    """Drains and closes the process worker if one was created, backing ``shutdown()``.
+    """Drains and closes the process worker, or closes an orphan-only sink, backing ``shutdown()``.
 
     The ``atexit`` registration binds this function, so the exit path gets the bounded form
     and its default (SPEC-027 FR-004) — an unbounded join in an ``atexit`` handler is a
-    process that will not exit. Idempotent.
+    process that will not exit. Idempotent on both paths.
+
+    ``_orphan_retired`` is set unconditionally and read only when there is no worker, which is
+    what makes ``health().retired`` truthful for a process that shut down without ever
+    building one (SPEC-031 FR-006). No worker is created here to answer it: standing up a
+    thread at exit to prove there is nothing to drain is pure cost, the same refusal
+    :func:`_swap_sink` and :func:`_flush_worker` already make.
 
     Args:
       timeout: Seconds to wait for the drain, or ``None`` to wait indefinitely.
@@ -229,8 +336,12 @@ def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     Raises:
       None.
     """
+    global _orphan_retired
+    _orphan_retired = True
     if _worker is not None:
         _worker.shutdown(timeout)
+        return
+    _close_orphan_sink()
 
 
 def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> None:
@@ -301,6 +412,24 @@ def _worker_health() -> Health:
     created has not died, which is why SPEC-019 reports the terminal failure as a reason
     rather than an ``alive`` flag.
 
+    ``retired`` is the one field synthesized rather than zeroed (SPEC-031 FR-006). It records
+    an action the caller took, not a state of the worker, so it stays true in a process that
+    called ``shutdown()`` without ever building one — where it was previously vacuous, and the
+    whole snapshot read all-clear over a sink that had just been closed.
+    ``submitted_after_shutdown`` is deliberately **not** synthesized alongside it: SPEC-030
+    defines that count as submissions queued where nothing will drain them, and a later orphan
+    log is refused at the closed sink and announced instead. The two are not the same claim.
+
+    The synthesis also survives a worker built *after* that shutdown, which is why it is an
+    ``or`` rather than a fallback. An orphan-only ``shutdown()`` leaves ``_worker`` unset, so a
+    later ``@trace`` constructs a fresh worker whose own ``retired`` is ``False`` — and reading
+    that alone would say the process was never shut down, contradicting this function's own
+    guarantee one call earlier. The events that worker carries are not lost silently: against a
+    sink that guards its post-close state they raise and land in ``failed_batches`` (measured),
+    and against one that releases nothing on ``close()`` they genuinely still deliver. So the
+    detection is ``failed_batches`` there rather than SPEC-030's ``retired`` +
+    ``submitted_after_shutdown`` pair, which stays the signal for the path it was built for.
+
     Args:
       None.
 
@@ -312,8 +441,11 @@ def _worker_health() -> Health:
     """
     worker = _worker
     if worker is None:
-        return Health(queued=0, dropped=0, failed_batches=0)
-    return worker.health()
+        return Health(queued=0, dropped=0, failed_batches=0, retired=_orphan_retired)
+    health = worker.health()
+    if _orphan_retired and not health.retired:
+        return health._replace(retired=True)
+    return health
 
 
 def _flush(span: Span) -> None:

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

@@ -90,12 +90,15 @@ 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
+      retired: Whether ``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.
+        It is the one field ``decorator._worker_health`` synthesizes rather than zeroing, so
+        that a process which only ever logged outside a span — and therefore has no worker at
+        all — still reports its own shutdown truthfully (SPEC-031 FR-006).
       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
@@ -854,6 +857,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.