log-foundry 0.10.2.dev41__tar.gz → 0.10.2.dev43__tar.gz

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev41
+Version: 0.10.2.dev43
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -396,6 +396,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `get_baggage()` | Current baggage as a `dict`. A shallow copy — rebinding a key does not reach the library, but a nested mutable value is shared. |
 | `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
@@ -465,14 +466,20 @@ undoing the erasure. It never raises.
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
 receives already-built, batched event dicts and knows nothing about spans or context:
 
-```python
-class Sink(Protocol):
-    def emit(self, batch: list[dict[str, object]]) -> None: ...
-    def close(self) -> None: ...
+```
+emit(batch: list[dict[str, object]]) -> None
+close() -> None
 ```
 
+Satisfy it **structurally** — any object with those two methods is a sink, and every sink shipped
+here is one. You do not need to inherit. If you prefer to, `from log_foundry import Sink` gives you
+the protocol to annotate against or subclass; both methods are abstract, so a subclass that
+misspells `emit` fails at construction rather than silently accepting every batch and delivering
+nothing.
+
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
-call falls back to `StdoutSink()`. Sinks are **not** re-exported at the top level — import each
+call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
+`SinkDeliveryError`, `SinkLosses` and `read_losses`; the **concrete sinks** are not, so import each
 from its own module, e.g. `from log_foundry.sinks.sqs import SQSSink`.
 
 A few conventions hold across every sink below:
@@ -728,11 +735,14 @@ loss-reporting apparatus is built on them:
   whole operation that assumes exclusivity. If it holds none, you need do nothing. The library
   cannot serialize this for you: it does not own the calling thread.
 
+- **The batch is borrowed, not given.** The list and the dicts in it may go to other sinks after
+  you — `MultiSink` hands the same objects to every child in turn — so copy before you redact or
+  reshape. A child that cleared the list in place left the next child with nothing, and no error
+  anywhere.
 - **Raise when you delivered none of the batch**, after your own retries are spent. That is the
   signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
   a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
-  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
-  propagates.
+  `log_foundry`) or any exception of your own — the contract is that *something* propagates.
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
@@ -756,7 +766,7 @@ separate from the transport one so a poll never waits on an in-flight send:
 
 ```python
 import threading
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry import SinkDeliveryError, SinkLosses
 
 class MySink:
     def __init__(self) -> None:
@@ -764,6 +774,7 @@ class MySink:
         self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
+        self.log_foundry_stop_signal: threading.Event | None = None  # optional; see below
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         if not batch:
@@ -799,6 +810,48 @@ class MySink:
 simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
 failed to deliver.
 
+`log_foundry_stop_signal` is optional in the same way, and is an attribute rather than a method.
+Declare it as a plain `threading.Event | None` initialised to `None` and the library assigns the
+worker's shutdown event to it; leave it out and you are simply never offered one. **Honour it in
+your retry backoff** — pass it to `Event.wait(timeout)` instead of calling `time.sleep`:
+
+```python
+        if self.log_foundry_stop_signal is not None:
+            self.log_foundry_stop_signal.wait(delay)   # returns early when shutdown starts
+        else:
+            time.sleep(delay)
+```
+
+There is one drain thread, so your backoff pauses *all* log delivery, and it is held across
+`shutdown()` — which joins that thread. A sink that sleeps through a 30-second backoff holds
+process exit for 30 seconds. The name is prefixed because the library assigns this attribute onto
+an object it does not own: a bare `stop_signal` would silently overwrite one you already had.
+
+If you write a **wrapper** sink, forward it to whatever actually holds the retry loop — a plain
+attribute on the wrapper is assigned, stops there, and the inner sink never sees it. Measured: a
+wrapper built from the leaf template above left an inner sink's 4-second backoff uninterrupted,
+`shutdown(timeout=30)` ran the full 30 seconds, `stopped_reason` read `"ShutdownTimeout"` and the
+sink was left open — against 0.00 s for the same sink configured directly. Use a property:
+
+```python
+class MyWrapper:
+    def __init__(self, inner) -> None:
+        self._inner = inner
+        self._stop_signal: threading.Event | None = None
+
+    @property
+    def log_foundry_stop_signal(self) -> threading.Event | None:
+        return self._stop_signal
+
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        self._inner.log_foundry_stop_signal = signal   # the one line that matters
+```
+
+Every wrapper shipped here — `MultiSink`, `FilteringSink`, `TransformSink`, `SyslogSink`,
+`LogstashSink`, `SentrySink` — does exactly this.
+
 ### Flushing and shutdown
 
 Delivery is off the hot path. When a span ends, its events are handed to a per-process

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/README.md

@@ -360,6 +360,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `get_baggage()` | Current baggage as a `dict`. A shallow copy — rebinding a key does not reach the library, but a nested mutable value is shared. |
 | `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
@@ -429,14 +430,20 @@ undoing the erasure. It never raises.
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
 receives already-built, batched event dicts and knows nothing about spans or context:
 
-```python
-class Sink(Protocol):
-    def emit(self, batch: list[dict[str, object]]) -> None: ...
-    def close(self) -> None: ...
+```
+emit(batch: list[dict[str, object]]) -> None
+close() -> None
 ```
 
+Satisfy it **structurally** — any object with those two methods is a sink, and every sink shipped
+here is one. You do not need to inherit. If you prefer to, `from log_foundry import Sink` gives you
+the protocol to annotate against or subclass; both methods are abstract, so a subclass that
+misspells `emit` fails at construction rather than silently accepting every batch and delivering
+nothing.
+
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
-call falls back to `StdoutSink()`. Sinks are **not** re-exported at the top level — import each
+call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
+`SinkDeliveryError`, `SinkLosses` and `read_losses`; the **concrete sinks** are not, so import each
 from its own module, e.g. `from log_foundry.sinks.sqs import SQSSink`.
 
 A few conventions hold across every sink below:
@@ -692,11 +699,14 @@ loss-reporting apparatus is built on them:
   whole operation that assumes exclusivity. If it holds none, you need do nothing. The library
   cannot serialize this for you: it does not own the calling thread.
 
+- **The batch is borrowed, not given.** The list and the dicts in it may go to other sinks after
+  you — `MultiSink` hands the same objects to every child in turn — so copy before you redact or
+  reshape. A child that cleared the list in place left the next child with nothing, and no error
+  anywhere.
 - **Raise when you delivered none of the batch**, after your own retries are spent. That is the
   signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
   a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
-  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
-  propagates.
+  `log_foundry`) or any exception of your own — the contract is that *something* propagates.
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
@@ -720,7 +730,7 @@ separate from the transport one so a poll never waits on an in-flight send:
 
 ```python
 import threading
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry import SinkDeliveryError, SinkLosses
 
 class MySink:
     def __init__(self) -> None:
@@ -728,6 +738,7 @@ class MySink:
         self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
+        self.log_foundry_stop_signal: threading.Event | None = None  # optional; see below
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         if not batch:
@@ -763,6 +774,48 @@ class MySink:
 simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
 failed to deliver.
 
+`log_foundry_stop_signal` is optional in the same way, and is an attribute rather than a method.
+Declare it as a plain `threading.Event | None` initialised to `None` and the library assigns the
+worker's shutdown event to it; leave it out and you are simply never offered one. **Honour it in
+your retry backoff** — pass it to `Event.wait(timeout)` instead of calling `time.sleep`:
+
+```python
+        if self.log_foundry_stop_signal is not None:
+            self.log_foundry_stop_signal.wait(delay)   # returns early when shutdown starts
+        else:
+            time.sleep(delay)
+```
+
+There is one drain thread, so your backoff pauses *all* log delivery, and it is held across
+`shutdown()` — which joins that thread. A sink that sleeps through a 30-second backoff holds
+process exit for 30 seconds. The name is prefixed because the library assigns this attribute onto
+an object it does not own: a bare `stop_signal` would silently overwrite one you already had.
+
+If you write a **wrapper** sink, forward it to whatever actually holds the retry loop — a plain
+attribute on the wrapper is assigned, stops there, and the inner sink never sees it. Measured: a
+wrapper built from the leaf template above left an inner sink's 4-second backoff uninterrupted,
+`shutdown(timeout=30)` ran the full 30 seconds, `stopped_reason` read `"ShutdownTimeout"` and the
+sink was left open — against 0.00 s for the same sink configured directly. Use a property:
+
+```python
+class MyWrapper:
+    def __init__(self, inner) -> None:
+        self._inner = inner
+        self._stop_signal: threading.Event | None = None
+
+    @property
+    def log_foundry_stop_signal(self) -> threading.Event | None:
+        return self._stop_signal
+
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        self._inner.log_foundry_stop_signal = signal   # the one line that matters
+```
+
+Every wrapper shipped here — `MultiSink`, `FilteringSink`, `TransformSink`, `SyslogSink`,
+`LogstashSink`, `SentrySink` — does exactly this.
+
 ### Flushing and shutdown
 
 Delivery is off the hot path. When a span ends, its events are handed to a per-process

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/pyproject.toml

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

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/__init__.py

@@ -4,15 +4,16 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _dist_version
 
 from log_foundry.api import critical, debug, error, info, set_baggage, warning
-from log_foundry.config import configure, get_config
+from log_foundry.config import Config, configure, get_config
 from log_foundry.context import (
     current_baggage_header,
     current_trace_context,
     current_traceparent,
+    get_baggage,
     reset_context,
 )
 from log_foundry.decorator import continue_trace, trace
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry.sinks.base import Sink, SinkDeliveryError, SinkLosses, read_losses
 from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
 
 try:
@@ -156,7 +157,9 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
 
 __all__ = [
     "DEFAULT_SHUTDOWN_TIMEOUT",
+    "Config",
     "Health",
+    "Sink",
     "SinkDeliveryError",
     "SinkLosses",
     "__version__",
@@ -169,9 +172,11 @@ __all__ = [
     "debug",
     "error",
     "flush",
+    "get_baggage",
     "get_config",
     "health",
     "info",
+    "read_losses",
     "reset_context",
     "set_baggage",
     "shutdown",

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/_lifecycle.py

@@ -165,11 +165,12 @@ def offer_stop_signal(sink: Sink, stop: threading.Event) -> None:
       None.
 
     Raises:
-      None. A sink whose ``stop_signal`` is a read-only property, or whose ``__setattr__``
+      None. A sink whose ``log_foundry_stop_signal`` is a read-only property, or whose
+      ``__setattr__``
         objects, loses interruptibility rather than preventing the caller from proceeding.
     """
     try:
-        if hasattr(sink, "stop_signal"):
-            sink.stop_signal = stop
+        if hasattr(sink, "log_foundry_stop_signal"):
+            sink.log_foundry_stop_signal = stop
     except Exception as exc:
         _diag.absorbed("handing the sink its stop signal", exc, "its backoff stays uninterruptible")

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/api.py

@@ -72,7 +72,7 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
       None. A logging call must never hand the application an exception from a destination
         it never chose to talk to; absorbed faults are reported through ``_diag``.
     """
-    baggage = context.get_baggage()
+    baggage = context._live_baggage()
     span = context.current_span()
     event: dict[str, object] | None = None
     if span is not None:

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/config.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+import threading
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink
 
 
-@dataclass
+@dataclass(frozen=True)
 class Config:
     """Process-wide settings stamped onto every event and consulted by the pipeline.
 
@@ -22,6 +23,13 @@ class Config:
     string is measured in UTF-8 bytes, an integer in the decimal length it renders as, sign
     included. An integer is also bounded by ``sys.get_int_max_str_digits()`` whenever that
     is lower, since a longer one cannot be rendered at all.
+
+    It is **frozen** (SPEC-034 FR-003). :func:`get_config` handed out this object, so assigning
+    to it retargeted what the config *reported* while every event continued to the sink the
+    worker had already captured — SPEC-030's defect reachable with no underscore in sight — and
+    assigning a ceiling bypassed :func:`_require_positive`, so ``max_value_bytes = 0`` was
+    accepted and emptied every event it touched. Both measured. :func:`configure` is the only
+    supported route to a change, and it rebinds the module global rather than mutating.
     """
 
     service: str = "unknown"
@@ -37,6 +45,25 @@ class Config:
 
 _config = Config()
 
+_config_lock = threading.Lock()
+"""Serializes the read-modify-write that replacing a frozen config now is.
+
+Freezing :class:`Config` turned each field assignment into a whole-object
+``replace()`` — a read of every field followed by a write of every field — and one of the two
+call sites, :func:`_ensure_sink`, runs on the **orphan logging path**, on whatever application
+thread called ``info()``. A stale snapshot there puts back the pre-``configure()`` ``service``,
+``version``, ``env``, ``defaults`` *and* ``sink``, permanently. Measured on the unlocked version:
+268 of 2000 trials shipped every later event with ``service="unknown"`` after one concurrent
+``info()``, against 0 before the freeze — a regression, and the SPEC-024 category of wrong data
+rather than lost data.
+
+It does **not** cover reads. :func:`_live_config` is one atomic global read and stays lock-free,
+so the per-event path pays nothing (SPEC-034 FR-003 AC-6). Lock ordering is one-way and stays
+that way: ``_ensure_sink`` is called with ``decorator._worker_lock`` held, and ``configure()``
+releases this lock before ``_swap_live_sink`` takes that one, so nothing acquires
+``_worker_lock`` underneath this.
+"""
+
 
 def _require_positive(name: str, value: int | None) -> None:
     """Rejects a non-positive ceiling.
@@ -127,24 +154,22 @@ def configure(
     _require_positive("max_keys", max_keys)
     _require_positive("max_depth", max_depth)
 
-    if service is not None:
-        _config.service = service
-    if version is not None:
-        _config.version = version
-    if env is not None:
-        _config.env = env
-    if sink is not None:
-        _config.sink = sink
-    if defaults is not None:
-        _config.defaults = dict(defaults)
-    if max_value_bytes is not None:
-        _config.max_value_bytes = max_value_bytes
-    if max_stack_bytes is not None:
-        _config.max_stack_bytes = max_stack_bytes
-    if max_keys is not None:
-        _config.max_keys = max_keys
-    if max_depth is not None:
-        _config.max_depth = max_depth
+    changed: dict[str, object] = {
+        name: value
+        for name, value in (
+            ("service", service),
+            ("version", version),
+            ("env", env),
+            ("sink", sink),
+            ("defaults", None if defaults is None else dict(defaults)),
+            ("max_value_bytes", max_value_bytes),
+            ("max_stack_bytes", max_stack_bytes),
+            ("max_keys", max_keys),
+            ("max_depth", max_depth),
+        )
+        if value is not None
+    }
+    _rebind(**changed)
 
     _ensure_sink()
 
@@ -181,13 +206,75 @@ def _swap_live_sink(sink: Sink) -> None:
 
 
 def get_config() -> Config:
-    """Returns the current global config singleton.
+    """Returns the current global config, for reading.
+
+    **Mutating what this returns raises** (SPEC-034 FR-003). It used to hand back the live
+    singleton, so assigning to it retargeted what the config *reported* while every event
+    continued to the sink the worker had already captured, and assigning a ceiling bypassed the
+    validation :func:`configure` performs — ``max_value_bytes = 0`` was accepted and emptied
+    every event it touched. Both measured. :func:`configure` is the only route to a change.
+
+    It is a **copy**, not the frozen original, and ``defaults`` is copied with it. A caller who
+    defeats the freeze — ``object.__setattr__`` reaches through any frozen dataclass — then
+    edits an object the library does not read, rather than the live config; and ``defaults`` is
+    a plain mutable ``dict``, so sharing it would leave the freeze cosmetic at the one field
+    that is not a scalar. ``dataclasses.replace`` alone does **not** do this: it shares the
+    dict, which was measured while building this.
+
+    Args:
+      None.
+
+    Returns:
+      A copy of the process-wide :class:`Config`, with its own ``defaults``.
+
+    Raises:
+      None.
+    """
+    return replace(_config, defaults=dict(_config.defaults))
+
+
+def _rebind(**changed: object) -> None:
+    """Replaces the module-global config with a copy carrying the changed fields.
+
+    :class:`Config` is frozen (SPEC-034 FR-003), so a change is a new object and a rebinding of
+    the global rather than an assignment to a field. It is **one** replacement for the whole
+    call, not one per field: nine rebindings would allocate nine configs and, worse, would leave
+    a window in which another thread reads a half-applied config — a `service` from the new call
+    beside a `sink` from the old one, stamped onto real events.
+
+    Rebinding is safe only because no module imports ``_config`` by value; a
+    ``from log_foundry.config import _config`` anywhere would hold the pre-rebind object forever,
+    which is why a test asserts the absence rather than a comment claiming it.
+
+    Args:
+      **changed: Field names and their new values. Fields not named keep their current value.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    global _config
+    with _config_lock:
+        _config = replace(_config, **changed)  # type: ignore[arg-type]
+
+
+def _live_config() -> Config:
+    """Returns the config object itself, for callers inside the package.
+
+    :func:`get_config` copies, because it is public and a caller must not be able to reach the
+    live object through it. ``model.build_event`` reads the config **one to three times per
+    event**, so routing that through the public accessor would allocate a ``Config`` and a
+    ``defaults`` dict per event. The freeze is a guarantee to the library's *users*, not one the
+    library needs against itself, so internal callers read the live object and treat it as
+    read-only — the same split :func:`context._live_baggage` makes for baggage.
 
     Args:
       None.
 
     Returns:
-      The process-wide :class:`Config`.
+      The live process-wide :class:`Config`.
 
     Raises:
       None.
@@ -203,6 +290,14 @@ def _ensure_sink() -> Sink:
     user has not called ``configure()`` yet. The local import defers the ``sinks``
     dependency and avoids a top-level import cycle (arch §7).
 
+    It is called on the **orphan logging path**, on arbitrary application threads, so the
+    default is resolved under :data:`_config_lock` with a double check and the global is re-read
+    inside it (SPEC-034 FR-003). Returning a freshly built local instead handed two racing
+    threads two different ``StdoutSink`` objects — measured 996 of 3000 trials — one of which
+    then received events and was referenced by nothing, so nothing closed it (SPEC-031 FR-006).
+    The unlocked read above it is the fast path: once a sink is configured this is one atomic
+    global read and no lock at all.
+
     Args:
       None.
 
@@ -212,8 +307,17 @@ def _ensure_sink() -> Sink:
     Raises:
       None.
     """
-    if _config.sink is None:
-        from log_foundry.sinks.stdout import StdoutSink
-
-        _config.sink = StdoutSink()
-    return _config.sink
+    global _config
+    sink_now = _config.sink
+    if sink_now is not None:
+        return sink_now
+
+    from log_foundry.sinks.stdout import StdoutSink
+
+    with _config_lock:
+        if _config.sink is None:
+            _config = replace(_config, sink=StdoutSink())
+        resolved = _config.sink
+    if resolved is None:  # pragma: no cover - unreachable; the branch above just set it
+        raise RuntimeError("the default sink could not be resolved")
+    return resolved

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/context.py

@@ -96,18 +96,48 @@ def pop_span(token: contextvars.Token[tuple[Span, ...]]) -> None:
 
 
 def get_baggage() -> dict[str, object]:
-    """Returns the current trace's baggage, which must not be mutated in place.
+    """Returns a copy of the current trace's baggage.
 
     The trace's own keys are discarded when the enclosing root span closes, restoring the
     baggage in effect before it, so a later trace sees only a process-level default set
     before any span opened. With no span open at all nothing releases them and they
     accumulate for the life of the context; :func:`reset_context` is the release there.
 
+    It is a **shallow** copy (SPEC-034 FR-005). This became public at 1.0, and a public accessor
+    that hands out the live mapping documented as "do not mutate" is FR-003's ``get_config()``
+    defect under another name. Shallow rather than deep because :func:`set_baggage` accepts
+    arbitrary values: a deep copy would run user objects through ``copy.deepcopy`` inside a
+    getter that must never raise, which trades a narrow sharing bound for a wide new failure —
+    and the library never mutates a baggage value either, so the sharing is only reachable
+    through the caller's own object. The library's own hot path does not pay even for the
+    shallow copy: :func:`_live_baggage` is the internal read, for the reason FR-003 AC-6 gives.
+
+    Args:
+      None.
+
+    Returns:
+      A shallow copy of the baggage mapping. Rebinding a key does not affect the library; a
+        nested mutable value is shared, and mutating one *does* reach every later event.
+
+    Raises:
+      None.
+    """
+    return dict(_baggage.get())
+
+
+def _live_baggage() -> dict[str, object]:
+    """Returns the baggage mapping itself, for callers inside the package.
+
+    :func:`api._log` reads baggage once per event, so a copy here would allocate per event —
+    the cost FR-003 AC-6 measures and refuses on the config's own hot path. Callers must treat
+    the result as read-only; the freeze is a guarantee to the library's *users*, not one the
+    library needs against itself.
+
     Args:
       None.
 
     Returns:
-      The baggage mapping, to be treated as read-only.
+      The live baggage mapping.
 
     Raises:
       None.
@@ -300,7 +330,7 @@ def current_baggage_header() -> str:
     Raises:
       None.
     """
-    return format_baggage_header(get_baggage())
+    return format_baggage_header(_live_baggage())
 
 
 def format_baggage_header(baggage: dict[str, object]) -> str:

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/decorator.py

@@ -853,7 +853,7 @@ def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
         guard.
     """
     span.events.append(end_event(span, status, exc))
-    backfill_baggage(span, context.get_baggage())
+    backfill_baggage(span, context._live_baggage())
     _flush(span)
 
 

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/model.py

@@ -8,7 +8,7 @@ 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.config import _live_config
 from log_foundry.ids import new_log_id
 from log_foundry.sanitize import sanitize_fields, truncate_str, truncate_tail
 
@@ -93,7 +93,7 @@ def build_event(
     Raises:
       None.
     """
-    cfg = get_config()
+    cfg = _live_config()
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
     safe, clipped = sanitize_fields(merged, cfg=cfg)
     bounded_message, message_clipped = truncate_str(message, cfg.max_value_bytes)
@@ -236,7 +236,7 @@ def end_event(
     event["duration_ms"] = (time.monotonic() - span.start_ts) * 1000.0
     event["status"] = status
     if exc is not None:
-        error, clipped = _error_fields(exc, cfg=get_config())
+        error, clipped = _error_fields(exc, cfg=_live_config())
         event["error"] = error
         if clipped:
             event[_TRUNCATED] = True
@@ -269,7 +269,7 @@ def backfill_baggage(span: Span, baggage: dict[str, object]) -> None:
     """
     if not baggage:
         return
-    safe, clipped = sanitize_fields(baggage, cfg=get_config())
+    safe, clipped = sanitize_fields(baggage, cfg=_live_config())
     for event in span.events:
         if event.get("message") in (_START_MESSAGE, _END_MESSAGE):
             fields = event.get("fields")

{log_foundry-0.10.2.dev41 → log_foundry-0.10.2.dev43}/src/log_foundry/sinks/_socket.py

@@ -133,7 +133,7 @@ class SocketTransport:
         self._sock: socket.socket | None = None
         self.failed = 0
         self._counter_lock = threading.Lock()
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self._lock = threading.Lock()
         self._closed = False
 
@@ -243,7 +243,7 @@ class SocketTransport:
             except OSError as err:
                 self._reset()
                 if attempt < self._max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += 1