log-foundry 0.10.2.dev108__tar.gz → 0.10.2.dev110__tar.gz

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev108
+Version: 0.10.2.dev110
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/pyproject.toml

@@ -74,7 +74,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev108"
+version = "0.10.2.dev110"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/__init__.py

@@ -15,8 +15,14 @@ from log_foundry.context import (
 )
 from log_foundry.decorator import continue_trace, trace
 from log_foundry.results import ContinueResult, FlushResult
-from log_foundry.sinks.base import Sink, SinkDeliveryError, SinkLosses, read_losses
-from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
+from log_foundry.sinks.base import (
+    Sink,
+    SinkDeliveryError,
+    SinkLosses,
+    flush_sink,
+    read_losses,
+)
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_SWAP_TIMEOUT, Health
 
 try:
     __version__ = _dist_version("log-foundry")
@@ -95,7 +101,9 @@ def health() -> Health:
 
     Returns:
       The snapshot: ``queued``, ``dropped``, ``failed_batches``, ``stopped_reason``, ``sink``,
-      ``retired``, ``submitted_after_shutdown`` and ``incomplete_swaps``. ``retired`` says
+      ``retired``, ``submitted_after_shutdown``, ``incomplete_swaps``, ``closing_sinks``,
+      ``inherited_sink``, ``orphan_lost`` and ``in_span_lost`` — every field, since a counter
+      documented nowhere is a loss nobody looks for. ``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`.
@@ -112,7 +120,11 @@ def health() -> Health:
       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
-      on total failure counts the attempt and hands the batch back for the worker to retry. A
+      on total failure counts the attempt and hands the batch back for the worker to retry.
+      ``inherited_sink`` is a state and not a fault: it says **whether** the sink this process
+      last installed for delivery is one it inherited across a ``fork`` and may not release,
+      which is what explains a handle still open after :func:`shutdown` (SPEC-042). ``orphan_lost`` and ``in_span_lost``
+      are the two terms above that describe no worker at all, and the alert idiom ends on them. A
       process that has never logged has no worker, and asking does not create one — the
       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
@@ -176,6 +188,7 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
 
 __all__ = [
     "DEFAULT_SHUTDOWN_TIMEOUT",
+    "DEFAULT_SWAP_TIMEOUT",
     "Config",
     "ContinueResult",
     "FlushResult",
@@ -193,6 +206,7 @@ __all__ = [
     "debug",
     "error",
     "flush",
+    "flush_sink",
     "get_baggage",
     "get_config",
     "health",

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/config.py

@@ -9,10 +9,12 @@ from typing import TYPE_CHECKING
 from log_foundry import _lifecycle
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
+
     from log_foundry.sinks.base import Sink
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class Config:
     """Process-wide settings stamped onto every event and consulted by the pipeline.
 
@@ -92,7 +94,7 @@ def configure(
     version: str | None = None,
     env: str | None = None,
     sink: Sink | None = None,
-    defaults: dict[str, object] | None = None,
+    defaults: Mapping[str, object] | None = None,
     max_value_bytes: int | None = None,
     max_stack_bytes: int | None = None,
     max_keys: int | None = None,
@@ -147,7 +149,9 @@ def configure(
       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.
+      defaults: Fields merged into every event at the lowest precedence. Any ``Mapping`` is
+        accepted and a copy is stored, so a later edit to the caller's own object does not
+        reach the config (SPEC-051 FR-002).
       max_value_bytes: Per-value ceiling, in UTF-8 bytes or rendered digits.
       max_stack_bytes: Ceiling for ``error.stack`` alone.
       max_keys: Ceiling on the entries of one mapping or sequence.

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/context.py

@@ -13,17 +13,20 @@ if TYPE_CHECKING:
 
 __all__ = [
     "current_baggage_header",
-    "current_span",
     "current_trace_context",
     "current_traceparent",
     "get_baggage",
-    "pop_baggage_scope",
-    "pop_span",
-    "push_baggage_scope",
-    "push_span",
     "reset_context",
     "set_baggage",
 ]
+"""Exactly the six names ``log_foundry`` re-exports (SPEC-051 FR-003).
+
+The five that left -- ``current_span``, ``push_span``, ``pop_span``, ``push_baggage_scope``
+and ``pop_baggage_scope`` -- are internal and stay importable; what was withdrawn is the
+claim, not the symbol. ``current_span`` is why this matters: it hands back a **mutable**
+:class:`~.model.Span`, which is what :func:`current_trace_context` exists to keep callers
+away from, and a name still in ``__all__`` at ``1.0`` could not be withdrawn afterwards.
+"""
 
 _span_stack: contextvars.ContextVar[tuple[Span, ...]] = contextvars.ContextVar(
     "log_foundry_span_stack", default=()

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/decorator.py

@@ -22,6 +22,7 @@ from log_foundry.results import ContinueResult
 
 if TYPE_CHECKING:
     import contextvars
+    from collections.abc import Mapping
 
 
 __all__ = ["continue_trace", "trace"]
@@ -631,7 +632,7 @@ def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
 def trace(func: F) -> F: ...
 @overload
 def trace(
-    *, name: str | None = ..., defaults: dict[str, object] | None = ...
+    *, name: str | None = ..., defaults: Mapping[str, object] | None = ...
 ) -> Callable[[F], F]: ...
 
 
@@ -639,14 +640,18 @@ def trace(
     func: F | None = None,
     *,
     name: str | None = None,
-    defaults: dict[str, object] | None = None,
+    defaults: Mapping[str, object] | None = None,
 ) -> F | Callable[[F], F]:
     """Traces a function call as a span, usable bare as ``@trace`` or with arguments.
 
     Args:
       func: The function being decorated when used bare, otherwise ``None``.
       name: Overrides the span name, which defaults to ``func.__qualname__``.
-      defaults: Per-decorator default fields added to every event on the span.
+      defaults: Per-decorator default fields added to every event on the span. Any
+        ``Mapping`` is accepted, and a copy is taken **once here**, at decoration — not per
+        call. Before SPEC-051 FR-002 the caller's own object was bound to every span and read
+        on the per-event path, so editing it after decoration changed later spans; that is
+        tolerable for a ``dict`` and is not for a ``Mapping`` whose ``keys()`` is user code.
 
     Returns:
       The wrapped function, or a decorator when called with arguments.
@@ -654,6 +659,7 @@ def trace(
     Raises:
       None.
     """
+    span_defaults = None if defaults is None else dict(defaults)
 
     def decorate(fn: F) -> F:
         """Wraps one function, selecting the sync or async wrapper at decoration time.
@@ -698,7 +704,7 @@ def trace(
                 Raises:
                   BaseException: Whatever the wrapped coroutine raises, unchanged.
                 """
-                span, token, scope = _begin(name or fn.__qualname__, defaults)
+                span, token, scope = _begin(name or fn.__qualname__, span_defaults)
                 status, error = "ok", None
                 try:
                     result = await fn(*args, **kwargs)
@@ -734,7 +740,7 @@ def trace(
             Raises:
               BaseException: Whatever the wrapped function raises, unchanged.
             """
-            span, token, scope = _begin(name or fn.__qualname__, defaults)
+            span, token, scope = _begin(name or fn.__qualname__, span_defaults)
             status, error = "ok", None
             try:
                 result = fn(*args, **kwargs)

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/results.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass
 __all__ = ["ContinueResult", "FlushResult"]
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class _Result:
     """A verdict that reads as a boolean and can say why (SPEC-034 FR-007).
 

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/base.py

@@ -20,7 +20,7 @@ class SinkDeliveryError(Exception):
     """
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class SinkLosses:
     """What a sink discarded or could not confirm, cumulative for its lifetime (FR-002).
 
@@ -30,6 +30,14 @@ class SinkLosses:
     lost. ``health().failed_batches`` is the worker-level record of a batch given up on for
     good; this is the sink-level record of everything that did not go through first time.
 
+    Construction is **keyword-only** (SPEC-051 FR-001), which is a break for a sink written
+    against ``0.x``: passing the two counters positionally now raises, and because
+    :func:`read_losses`
+    swallows a raising accessor by design, that sink's loss reporting degrades to ``None`` —
+    "reports nothing" — rather than to an error anyone sees. One keyword each is the fix. The
+    same decision empties ``__match_args__``, so a positional ``case SinkLosses(d, f):`` no
+    longer matches while ``case SinkLosses(dropped=d, failed=f):`` still does.
+
     Attributes:
       dropped: An event the sink discarded before attempting delivery, usually one the
         destination could never have accepted as built, so the fix is upstream in what the

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/datadog.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import json
+from typing import Unpack
 
-from log_foundry.sinks.http import HTTPSink, merge_headers
+from log_foundry.sinks.http import HTTPPlatformKwargs, HTTPSink, merge_headers
 
 __all__ = ["DatadogSink"]
 
@@ -45,7 +46,7 @@ class DatadogSink(HTTPSink):
         site: str = "datadoghq.com",
         service: str | None = None,
         ddtags: str | None = None,
-        **http_kwargs: object,
+        **http_kwargs: Unpack[HTTPPlatformKwargs],
     ) -> None:
         """Points the sink at a Datadog site's logs intake.
 
@@ -54,7 +55,9 @@ class DatadogSink(HTTPSink):
           site: The Datadog site, which selects the intake host.
           service: Overrides the event's own ``service``, or ``None`` to keep it.
           ddtags: Tags applied to every entry, or ``None`` for none.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPPlatformKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, which this sink pins to Datadog's JSON array.
 
         Returns:
           None.
@@ -67,7 +70,9 @@ class DatadogSink(HTTPSink):
         headers = merge_headers({"DD-API-KEY": api_key}, http_kwargs)
         super().__init__(
             f"https://http-intake.logs.{site}/api/v2/logs",
-            headers=headers, body_format="json_array", **http_kwargs,  # type: ignore[arg-type]
+            headers=headers,
+            body_format="json_array",
+            **http_kwargs,  # type: ignore[misc]
         )
 
     def _render(self, event: dict[str, object]) -> str:

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/elasticsearch.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import json
+from typing import Unpack
 
 from log_foundry import _diag
 from log_foundry.sinks._batch import usable_results
 from log_foundry.sinks.base import SinkLosses
-from log_foundry.sinks.http import HTTPSink, _Item
+from log_foundry.sinks.http import HTTPRetryKwargs, HTTPSink, _Item
 
 __all__ = ["ElasticsearchSink", "OpenSearchSink"]
 
@@ -48,14 +49,17 @@ class ElasticsearchSink(HTTPSink):
     MAX_BATCH_BYTES = 10_000_000
 
     def __init__(self, url: str, *, index: str, auth: str | tuple[str, str] | None = None,
-                 **http_kwargs: object) -> None:
+                 **http_kwargs: Unpack[HTTPRetryKwargs]) -> None:
         """Points the sink at a cluster's ``_bulk`` endpoint.
 
         Args:
           url: The cluster base URL, to which ``/_bulk`` is appended.
           index: The target index named in every action line.
           auth: A bearer token, or a ``(user, password)`` pair for basic auth.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPRetryKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, pinned to the bulk API's NDJSON, and ``auth``, which is a
+            parameter of this sink's own.
 
         Returns:
           None.
@@ -65,7 +69,7 @@ class ElasticsearchSink(HTTPSink):
         """
         self._index = index
         super().__init__(
-            url.rstrip("/") + "/_bulk", auth=auth, body_format="ndjson", **http_kwargs  # type: ignore[arg-type]
+            url.rstrip("/") + "/_bulk", auth=auth, body_format="ndjson", **http_kwargs
         )
         self.item_errors = 0
         self.dropped_unadjudicated = 0

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/filtering.py

@@ -186,9 +186,9 @@ class FilteringSink:
 
         Returns:
           The inner sink's losses. ``None`` passes through unchanged rather than becoming
-          ``SinkLosses(0, 0)``: FR-003 distinguishes "the sink reports nothing" from "the sink
-          reports no loss", and flattening the two would claim a clean bill of health on a sink
-          that never gave one.
+          ``SinkLosses(dropped=0, failed=0)``: FR-003 distinguishes "the sink reports
+          nothing" from "the sink reports no loss", and flattening the two would claim a
+          clean bill of health on a sink that never gave one.
 
         Raises:
           None.

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/honeycomb.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import json
+from typing import Unpack
 
-from log_foundry.sinks.http import HTTPSink, merge_headers
+from log_foundry.sinks.http import HTTPPlatformKwargs, HTTPSink, merge_headers
 
 __all__ = ["HoneycombSink"]
 
@@ -39,7 +40,7 @@ class HoneycombSink(HTTPSink):
         dataset: str,
         *,
         url: str = "https://api.honeycomb.io",
-        **http_kwargs: object,
+        **http_kwargs: Unpack[HTTPPlatformKwargs],
     ) -> None:
         """Points the sink at a dataset's batch endpoint.
 
@@ -47,7 +48,9 @@ class HoneycombSink(HTTPSink):
           api_key: The key sent as ``X-Honeycomb-Team``.
           dataset: The target dataset, which forms part of the path.
           url: The API base URL.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPPlatformKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, which this sink pins to Honeycomb's JSON array.
 
         Returns:
           None.
@@ -58,7 +61,9 @@ class HoneycombSink(HTTPSink):
         headers = merge_headers({"X-Honeycomb-Team": api_key}, http_kwargs)
         super().__init__(
             f"{url.rstrip('/')}/1/batch/{dataset}",
-            headers=headers, body_format="json_array", **http_kwargs,  # type: ignore[arg-type]
+            headers=headers,
+            body_format="json_array",
+            **http_kwargs,  # type: ignore[misc]
         )
 
     def _render(self, event: dict[str, object]) -> str:

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/http.py

@@ -8,17 +8,23 @@ import threading
 import urllib.error
 import urllib.request
 from base64 import b64encode
+from collections.abc import Callable  # noqa: TC003
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, NoReturn
+from typing import Any, NoReturn, TypedDict
 
 from log_foundry import _diag
 from log_foundry.sinks._retry import clamp_server_delay, wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-__all__ = ["HTTPSink", "merge_headers"]
+__all__ = [
+    "HTTPAuthKwargs",
+    "HTTPForwardKwargs",
+    "HTTPKwargs",
+    "HTTPPlatformKwargs",
+    "HTTPRetryKwargs",
+    "HTTPSink",
+    "merge_headers",
+]
 
 _BACKOFF_BASE = 0.1
 
@@ -196,7 +202,50 @@ def _no_redirect_opener() -> Callable[..., Any]:
     return urllib.request.build_opener(_NoRedirect()).open
 
 
-def merge_headers(base: dict[str, str], http_kwargs: dict[str, object]) -> dict[str, str]:
+class HTTPForwardKwargs(TypedDict, total=False):
+    """The :class:`HTTPSink` keywords every platform sink in this family can forward.
+
+    Five shapes, composed by inheritance so each key is declared exactly once, replace the
+    ``**http_kwargs: object`` that let ``timeout="not-a-float"`` past ``mypy`` and past
+    construction (SPEC-051 FR-005). A platform sink cannot forward a keyword it sets itself or
+    shadows with a parameter of its own — ``mypy`` refuses a ``**kwargs`` TypedDict key that
+    collides with a named parameter — so this is the intersection and the four below widen it.
+    Every annotation matches ``HTTPSink.__init__``'s, and a roster test holds them there.
+    """
+
+    method: str
+    headers: dict[str, str] | None
+    gzip: bool
+    max_retry_after: float
+    max_batch_count: int | None
+    max_batch_bytes: int | None
+    opener: Callable[..., Any] | None
+
+
+class HTTPRetryKwargs(HTTPForwardKwargs, total=False):
+    """:class:`HTTPForwardKwargs` plus the two a sink with a single transport does not own."""
+
+    timeout: float
+    max_retries: int
+
+
+class HTTPAuthKwargs(HTTPForwardKwargs, total=False):
+    """:class:`HTTPForwardKwargs` plus ``auth``, for a sink taking no credentials of its own."""
+
+    auth: str | tuple[str, str] | None
+
+
+class HTTPPlatformKwargs(HTTPRetryKwargs, HTTPAuthKwargs, total=False):
+    """Both of those: for a sink that owns only the body format."""
+
+
+class HTTPKwargs(HTTPPlatformKwargs, total=False):
+    """Every keyword :class:`HTTPSink` accepts besides its positional ``url``."""
+
+    body_format: str
+
+
+def merge_headers(base: dict[str, str], http_kwargs: HTTPForwardKwargs) -> dict[str, str]:
     """Merges a platform sink's own headers with any caller-supplied ones, caller winning.
 
     This is shared by the SaaS sinks that set a fixed auth header — Datadog, Splunk, New Relic,
@@ -205,7 +254,11 @@ def merge_headers(base: dict[str, str], http_kwargs: dict[str, object]) -> dict[
     Args:
       base: The sink's own headers, updated in place.
       http_kwargs: The caller's keyword arguments, mutated by popping ``headers`` out so the
-        rest can be forwarded to :class:`HTTPSink` without a duplicate argument.
+        rest can be forwarded to :class:`HTTPSink` without a duplicate argument. Typed as the
+        narrowest shape (SPEC-051 FR-005); every wider one is assignable to it, and ``pop`` is
+        allowed because each key is ``total=False``. The pop is why a caller may still pass
+        ``headers``, and — since it happens *here*, in another function — why ``mypy`` reports
+        the caller's own forwarding call as a possible duplicate anyway.
 
     Returns:
       The merged headers.

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/logstash.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Unpack
 
 if TYPE_CHECKING:
     import threading
@@ -11,7 +11,7 @@ if TYPE_CHECKING:
 from log_foundry import _lifecycle
 from log_foundry.sinks._socket import DEFAULT_MAX_DATAGRAM_BYTES, SocketTransport
 from log_foundry.sinks.base import SinkLosses
-from log_foundry.sinks.http import HTTPSink
+from log_foundry.sinks.http import HTTPAuthKwargs, HTTPSink
 
 __all__ = ["LogstashSink"]
 
@@ -90,7 +90,7 @@ class LogstashSink:
         timeout: float = 5.0,
         max_retries: int = 3,
         max_datagram_bytes: int = DEFAULT_MAX_DATAGRAM_BYTES,
-        **http_kwargs: object,
+        **http_kwargs: Unpack[HTTPAuthKwargs],
     ) -> None:
         """Selects and builds exactly one backend.
 
@@ -110,7 +110,11 @@ class LogstashSink:
           max_datagram_bytes: In UDP socket mode, the largest datagram to attempt; a frame over
             it is dropped and counted rather than sent, retried and abandoned (SPEC-038 FR-007).
             Ignored in HTTP mode and over TCP, which is a stream.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink` in HTTP mode.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink` in HTTP mode,
+            typed as ``HTTPAuthKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, ``timeout`` and ``max_retries``, each a parameter of this sink's
+            own: the last two because socket mode uses them, and ``body_format`` because it is
+            validated in both modes and defaults differently here.
 
         Returns:
           None.
@@ -127,7 +131,7 @@ class LogstashSink:
         if url is not None:
             self._http: HTTPSink | None = HTTPSink(
                 url, body_format=body_format, timeout=timeout, max_retries=max_retries,
-                **http_kwargs,  # type: ignore[arg-type]
+                **http_kwargs,
             )
             self._socket: SocketTransport | None = None
         elif host is not None and port is not None:

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/loki.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import json
+from typing import Unpack
 
 from log_foundry.sinks._time import epoch_nanos
-from log_foundry.sinks.http import HTTPSink, _Item
+from log_foundry.sinks.http import HTTPPlatformKwargs, HTTPSink, _Item
 
 __all__ = ["LokiSink"]
 
@@ -48,13 +49,15 @@ class LokiSink(HTTPSink):
     MAX_BATCH_BYTES = 4_000_000
 
     def __init__(self, url: str, *, labels: tuple[str, ...] = ("service", "env", "level"),
-                 **http_kwargs: object) -> None:
+                 **http_kwargs: Unpack[HTTPPlatformKwargs]) -> None:
         """Points the sink at a Loki push endpoint.
 
         Args:
           url: The Loki base URL, to which the push path is appended.
           labels: The event keys promoted to stream labels.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPPlatformKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, which this sink pins to Loki's JSON array.
 
         Returns:
           None.
@@ -64,7 +67,7 @@ class LokiSink(HTTPSink):
         """
         self._labels = labels
         super().__init__(
-            url.rstrip("/") + _PUSH_PATH, body_format="json_array", **http_kwargs  # type: ignore[arg-type]
+            url.rstrip("/") + _PUSH_PATH, body_format="json_array", **http_kwargs
         )
 
     def _render(self, event: dict[str, object]) -> str:

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/newrelic.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from log_foundry.sinks.http import HTTPSink, merge_headers
+from typing import Unpack
+
+from log_foundry.sinks.http import HTTPPlatformKwargs, HTTPSink, merge_headers
 
 __all__ = ["NewRelicSink"]
 
@@ -29,13 +31,18 @@ class NewRelicSink(HTTPSink):
     MAX_BATCH_COUNT = 1000
     MAX_BATCH_BYTES = 1_000_000
 
-    def __init__(self, api_key: str, *, region: str = "US", **http_kwargs: object) -> None:
+    def __init__(
+        self, api_key: str, *, region: str = "US",
+        **http_kwargs: Unpack[HTTPPlatformKwargs],
+    ) -> None:
         """Points the sink at a region's Log API endpoint.
 
         Args:
           api_key: The key sent as ``Api-Key``.
           region: The account region, matched case-insensitively, which selects the host.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPPlatformKwargs`` (SPEC-051 FR-005) — every keyword it takes except
+            ``body_format``, which this sink pins to New Relic's JSON array.
 
         Returns:
           None.
@@ -49,5 +56,7 @@ class NewRelicSink(HTTPSink):
         headers = merge_headers({"Api-Key": api_key}, http_kwargs)
         super().__init__(
             f"https://{_HOSTS[region]}/log/v1",
-            headers=headers, body_format="json_array", **http_kwargs,  # type: ignore[arg-type]
+            headers=headers,
+            body_format="json_array",
+            **http_kwargs,  # type: ignore[misc]
         )

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/sentry.py

@@ -12,10 +12,14 @@ from log_foundry import _diag, _lifecycle
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 from log_foundry.sinks.http import HTTPSink
 
-__all__ = ["SentrySink"]
+__all__ = ["Backend", "SentrySink"]
 
 Backend = Literal["auto", "sdk", "http"]
-"""Which transport a :class:`SentrySink` uses. Not exported: callers pass the literals."""
+"""Which transport a :class:`SentrySink` uses.
+
+Exported (SPEC-051 FR-004) because it is in a public signature: passing the literal is still
+the ordinary way to call, but a caller annotating a variable that holds one needs the name.
+"""
 
 _BACKENDS: Final = get_args(Backend)
 

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/splunk.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import json
+from typing import Unpack
 
 from log_foundry.sinks._time import epoch_seconds
-from log_foundry.sinks.http import HTTPSink, _Item, merge_headers
+from log_foundry.sinks.http import HTTPKwargs, HTTPSink, _Item, merge_headers
 
 __all__ = ["SplunkHECSink"]
 
@@ -44,7 +45,7 @@ class SplunkHECSink(HTTPSink):
         *,
         host: str | None = None,
         source: str = "log-foundry",
-        **http_kwargs: object,
+        **http_kwargs: Unpack[HTTPKwargs],
     ) -> None:
         """Points the sink at a collector endpoint.
 
@@ -53,7 +54,9 @@ class SplunkHECSink(HTTPSink):
           token: The HEC token sent in the ``Authorization`` header.
           host: The ``host`` stamped on each envelope, or ``None`` to omit it.
           source: The ``source`` stamped on each envelope.
-          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`.
+          **http_kwargs: Forwarded to :class:`~log_foundry.sinks.http.HTTPSink`, typed as
+            ``HTTPKwargs`` (SPEC-051 FR-005) — every keyword it takes, since this sink pins
+            none of them.
 
         Returns:
           None.
@@ -64,7 +67,7 @@ class SplunkHECSink(HTTPSink):
         self._host = host
         self._source = source
         headers = merge_headers({"Authorization": f"Splunk {token}"}, http_kwargs)
-        super().__init__(url, headers=headers, **http_kwargs)  # type: ignore[arg-type]
+        super().__init__(url, headers=headers, **http_kwargs)  # type: ignore[misc]
 
     def _render(self, event: dict[str, object]) -> str:
         """Serializes one event's HEC envelope (FR-008).

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/sqs.py

@@ -16,7 +16,7 @@ from log_foundry import _diag
 from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
-__all__ = ["SQSSink"]
+__all__ = ["DedupIdSource", "GroupIdSource", "SQSSink"]
 
 _BACKOFF_BASE = 0.1
 
@@ -27,7 +27,10 @@ MAX_ID_LEN = 128
 """SQS maximum length for ``MessageGroupId`` and ``MessageDeduplicationId``."""
 
 GroupIdSource = str | Callable[[dict[str, object]], str] | None
+"""What ``message_group_id=`` accepts: an event key to read, a callable, or ``None``."""
+
 DedupIdSource = Callable[[dict[str, object]], str] | None
+"""What ``message_deduplication_id=`` accepts: a callable, or ``None`` for a minted UUID."""
 
 
 class _Prepared(NamedTuple):

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/sinks/transform.py

@@ -154,9 +154,9 @@ class TransformSink:
 
         Returns:
           The inner sink's losses. ``None`` passes through unchanged rather than becoming
-          ``SinkLosses(0, 0)``: FR-003 distinguishes "the sink reports nothing" from "the sink
-          reports no loss", and flattening the two would claim a clean bill of health on a sink
-          that never gave one.
+          ``SinkLosses(dropped=0, failed=0)``: FR-003 distinguishes "the sink reports
+          nothing" from "the sink reports no loss", and flattening the two would claim a
+          clean bill of health on a sink that never gave one.
 
         Raises:
           None.

{log_foundry-0.10.2.dev108 → log_foundry-0.10.2.dev110}/src/log_foundry/worker.py

@@ -83,14 +83,17 @@ def _bounded_seconds(timeout: float | None) -> str:
         return "?"
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class Health:
     """A point-in-time snapshot of the worker's delivery counters (SPEC-017 FR-005).
 
-    ``stopped_reason``, ``sink``, and SPEC-030's three are defaulted and appended in that
-    order, so the zeroed snapshot in ``_lifecycle._worker_health`` — and any third-party
-    construction — keeps working, and attribute and index access to every earlier field stays
-    as it was.
+    Construction is **keyword-only** (SPEC-051 FR-001), which is what makes appending a field
+    safe: order is not part of the contract, so a new counter can go anywhere and no third-party
+    construction can bind to a position. It was previously ordered — every field after
+    ``failed_batches`` is defaulted and was appended in the order the specs landed. The claim
+    that a caller could also subscript this, carried here from the ``NamedTuple`` SPEC-034
+    replaced, was false from the moment it became a dataclass: ``len(health())`` raises
+    ``TypeError``, and ``README.md`` said the opposite correctly throughout.
 
     Attributes:
       queued: Submissions currently buffered. Approximate by nature: it is read without
@@ -148,8 +151,10 @@ class Health:
       closing_sinks: Swapped-out sinks whose ``close()`` is running *at this instant* — a live
         gauge rather than a counter, so it falls as well as rises. ~~the only field here that
         can fall~~ — struck (SPEC-034 AC-2c): ``queued`` falls on every drain. Those two are the
-        gauges and the other five integers are monotonic, which is the distinction an operator
-        alerting on "any non-zero" needs and which no name here encodes. A close is
+        only gauges and every other integer here is monotonic, which is the distinction an
+        operator alerting on "any non-zero" needs and which no name encodes. Stated as the rule
+        rather than as a count: it said "the other five" until SPEC-051, having gone stale when
+        SPEC-036 appended ``orphan_lost`` and ``in_span_lost`` and made it six. 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