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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev43
+Version: 0.10.2.dev45
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -68,6 +68,25 @@ pip install log-foundry          # core, zero dependencies
 pip install 'log-foundry[aws]'   # + boto3 for the SQS/SNS/Kinesis/Firehose sinks
 ```
 
+> **Breaking in `1.0.0`.** Three public shapes change once, before the API is frozen under
+> semantic versioning, because none of them could be changed afterwards without a major version:
+>
+> - **`health()` and `sink.losses()` return frozen dataclasses**, not `NamedTuple`s. Attribute
+>   access (`h.dropped`, `losses.failed`) is unchanged and is the whole contract; `len(h)`,
+>   `h[0]` and `queued, dropped, failed = health()` now raise `TypeError`. `Health` has gained a
+>   field in six consecutive specs and gains more — with no positions, that stops being breaking.
+> - **`flush()` returns a `FlushResult` and `continue_trace()` a `ContinueResult`**, each truthy
+>   or falsy with a `reason` naming *why*. `if lf.flush():` is unchanged; **`lf.flush() is True`
+>   is not** — the result is an object. A one-bit return could not grow a reason later without
+>   silently changing what `if flush():` means, which is why it moved now.
+> - **`SQSSink`'s injected client is keyword-only** (`SQSSink(url, client=…)`), **`SentrySink`
+>   injects through `client=`** rather than the old `sdk` keyword, with no alias, and the sink attribute the
+>   library assigns for interruptible backoff is **`log_foundry_stop_signal`**, not
+>   `stop_signal` — a prefixed name cannot silently overwrite one your own sink already uses.
+>
+> `echo`, `message` and `fields` are reserved parameter names on the emitters; pass fields of
+> those names through `fields={...}`, which also takes keys that are not Python identifiers.
+
 > **Renamed in 0.2.0: `log_forge` → `log_foundry`.** The import package now matches the
 > distribution name — `pip install log-foundry`, then `import log_foundry`. If you are on
 > `0.1.x`, update your imports; there is no compatibility shim. The project was originally
@@ -327,8 +346,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -341,7 +360,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -352,6 +372,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
@@ -392,7 +424,7 @@ def handler(event, context):
 
 | Call | Does |
 |---|---|
-| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. Returns a `ContinueResult`: truthy if adopted, else falsy with `reason` of `"nothing-supplied"` or `"rejected"`. The verdict is about the **trace context** — `baggage=` is merged independently and does not make it truthy. Never raises. |
 | `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). |
@@ -924,11 +956,12 @@ by design: a later level call is *refused* at the closed sink and announced on s
 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
-release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
-field keeps its position when a new one is appended, so attribute and index access stay stable.
+Read a snapshot **by attribute** (`h.dropped`), as above — that is the whole contract. `Health`
+and `SinkLosses` are frozen dataclasses, so `len(h)`, `h[0]` and `queued, dropped, failed =
+health()` all raise `TypeError`. They were `NamedTuple`s before `1.0.0` and the tuple shape is
+deliberately gone: `Health` has gained a field in six consecutive specs and gains more, and every
+one of those had to argue that the positions before it were undisturbed. There are no positions to
+disturb now, and adding a field is not a breaking change.
 
 `dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
 abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
@@ -942,12 +975,12 @@ which one you want depends on whether the process is about to end:
 ```python
 import log_foundry as lf
 
-lf.flush()      # drain to the sink and keep going; returns True when everything landed
+lf.flush()      # drain to the sink and keep going; truthy when everything landed
 lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained (30s cap)
 ```
 
 Both are bounded, because both can be called somewhere with a deadline. `flush(timeout=5.0)`
-returns `False` if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
+is falsy if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
 what it could, and reports `health().stopped_reason == "ShutdownTimeout"`. Passing `None` to
 either waits indefinitely, which is unsafe in any environment with an execution deadline.
 
@@ -972,11 +1005,30 @@ docstring states its own worst case.
 explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
 end of a short script. It is idempotent.
 
-`flush(timeout=5.0)` returns `True` when **nothing was lost while the call was outstanding** — the
-drain it forces reached the sink, and so did anything else the worker emitted while it waited its
-turn. It returns `False` on timeout, when the worker was already shut down or has died, and when
-any batch was abandoned inside that window. A `True` is evidence of delivery, not merely that a
-drain took place.
+`flush(timeout=5.0)` returns a **`FlushResult`**, truthy when **nothing was lost while the call
+was outstanding** — the drain it forces reached the sink, and so did anything else the worker
+emitted while it waited its turn. A truthy result is evidence of delivery, not merely that a drain
+took place.
+
+Falsy carries a `reason` saying which of five things happened, because they need different fixes:
+
+| `reason` | Means |
+|---|---|
+| `"timed-out"` | The drain did not finish inside your timeout — the destination is slow. |
+| `"retired"` | `shutdown()` was already called. Your lifecycle is wrong, not the sink. |
+| `"thread-died"` | The drain thread is gone; see `health().stopped_reason`. |
+| `"queue-full"` | Backpressure — the queue could not even accept the marker. |
+| `"abandoned"` | A batch was given up on after its retry budget. The destination is broken. |
+
+```python
+result = lf.flush(5.0)
+if not result:
+    print(f"undelivered: {result.reason}")
+```
+
+`if lf.flush():` works exactly as it always did. `lf.flush() is True` does **not** — the result is
+an object, not a bool. New `reason` values may appear in any release, so treat an unrecognised one
+as "some other failure" rather than matching exhaustively.
 
 The window starts when you call it. A batch abandoned *before* that is deliberately not its
 business: the loss is already counted in `health().failed_batches` and reported on stderr, and

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

@@ -32,6 +32,25 @@ pip install log-foundry          # core, zero dependencies
 pip install 'log-foundry[aws]'   # + boto3 for the SQS/SNS/Kinesis/Firehose sinks
 ```
 
+> **Breaking in `1.0.0`.** Three public shapes change once, before the API is frozen under
+> semantic versioning, because none of them could be changed afterwards without a major version:
+>
+> - **`health()` and `sink.losses()` return frozen dataclasses**, not `NamedTuple`s. Attribute
+>   access (`h.dropped`, `losses.failed`) is unchanged and is the whole contract; `len(h)`,
+>   `h[0]` and `queued, dropped, failed = health()` now raise `TypeError`. `Health` has gained a
+>   field in six consecutive specs and gains more — with no positions, that stops being breaking.
+> - **`flush()` returns a `FlushResult` and `continue_trace()` a `ContinueResult`**, each truthy
+>   or falsy with a `reason` naming *why*. `if lf.flush():` is unchanged; **`lf.flush() is True`
+>   is not** — the result is an object. A one-bit return could not grow a reason later without
+>   silently changing what `if flush():` means, which is why it moved now.
+> - **`SQSSink`'s injected client is keyword-only** (`SQSSink(url, client=…)`), **`SentrySink`
+>   injects through `client=`** rather than the old `sdk` keyword, with no alias, and the sink attribute the
+>   library assigns for interruptible backoff is **`log_foundry_stop_signal`**, not
+>   `stop_signal` — a prefixed name cannot silently overwrite one your own sink already uses.
+>
+> `echo`, `message` and `fields` are reserved parameter names on the emitters; pass fields of
+> those names through `fields={...}`, which also takes keys that are not Python identifiers.
+
 > **Renamed in 0.2.0: `log_forge` → `log_foundry`.** The import package now matches the
 > distribution name — `pip install log-foundry`, then `import log_foundry`. If you are on
 > `0.1.x`, update your imports; there is no compatibility shim. The project was originally
@@ -291,8 +310,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -305,7 +324,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -316,6 +336,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 
@@ -356,7 +388,7 @@ def handler(event, context):
 
 | Call | Does |
 |---|---|
-| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. `True` if adopted, `False` if nothing valid was supplied. Never raises. |
+| `continue_trace(traceparent=None, *, trace_id=None, parent_span_id=None, baggage=None)` | Adopt an inbound context. Returns a `ContinueResult`: truthy if adopted, else falsy with `reason` of `"nothing-supplied"` or `"rejected"`. The verdict is about the **trace context** — `baggage=` is merged independently and does not make it truthy. Never raises. |
 | `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). |
@@ -888,11 +920,12 @@ by design: a later level call is *refused* at the closed sink and announced on s
 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
-release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
-field keeps its position when a new one is appended, so attribute and index access stay stable.
+Read a snapshot **by attribute** (`h.dropped`), as above — that is the whole contract. `Health`
+and `SinkLosses` are frozen dataclasses, so `len(h)`, `h[0]` and `queued, dropped, failed =
+health()` all raise `TypeError`. They were `NamedTuple`s before `1.0.0` and the tuple shape is
+deliberately gone: `Health` has gained a field in six consecutive specs and gains more, and every
+one of those had to argue that the positions before it were undisturbed. There are no positions to
+disturb now, and adding a field is not a breaking change.
 
 `dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
 abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
@@ -906,12 +939,12 @@ which one you want depends on whether the process is about to end:
 ```python
 import log_foundry as lf
 
-lf.flush()      # drain to the sink and keep going; returns True when everything landed
+lf.flush()      # drain to the sink and keep going; truthy when everything landed
 lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained (30s cap)
 ```
 
 Both are bounded, because both can be called somewhere with a deadline. `flush(timeout=5.0)`
-returns `False` if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
+is falsy if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
 what it could, and reports `health().stopped_reason == "ShutdownTimeout"`. Passing `None` to
 either waits indefinitely, which is unsafe in any environment with an execution deadline.
 
@@ -936,11 +969,30 @@ docstring states its own worst case.
 explicitly when you need to be certain the tail reached the sink before a fast exit, e.g. at the
 end of a short script. It is idempotent.
 
-`flush(timeout=5.0)` returns `True` when **nothing was lost while the call was outstanding** — the
-drain it forces reached the sink, and so did anything else the worker emitted while it waited its
-turn. It returns `False` on timeout, when the worker was already shut down or has died, and when
-any batch was abandoned inside that window. A `True` is evidence of delivery, not merely that a
-drain took place.
+`flush(timeout=5.0)` returns a **`FlushResult`**, truthy when **nothing was lost while the call
+was outstanding** — the drain it forces reached the sink, and so did anything else the worker
+emitted while it waited its turn. A truthy result is evidence of delivery, not merely that a drain
+took place.
+
+Falsy carries a `reason` saying which of five things happened, because they need different fixes:
+
+| `reason` | Means |
+|---|---|
+| `"timed-out"` | The drain did not finish inside your timeout — the destination is slow. |
+| `"retired"` | `shutdown()` was already called. Your lifecycle is wrong, not the sink. |
+| `"thread-died"` | The drain thread is gone; see `health().stopped_reason`. |
+| `"queue-full"` | Backpressure — the queue could not even accept the marker. |
+| `"abandoned"` | A batch was given up on after its retry budget. The destination is broken. |
+
+```python
+result = lf.flush(5.0)
+if not result:
+    print(f"undelivered: {result.reason}")
+```
+
+`if lf.flush():` works exactly as it always did. `lf.flush() is True` does **not** — the result is
+an object, not a bool. New `reason` values may appear in any release, so treat an unrecognised one
+as "some other failure" rather than matching exhaustively.
 
 The window starts when you call it. A batch abandoned *before* that is deliberately not its
 business: the loss is already counted in `health().failed_batches` and reported on stderr, and

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

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

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

@@ -13,6 +13,7 @@ from log_foundry.context import (
     reset_context,
 )
 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
 
@@ -22,7 +23,7 @@ except PackageNotFoundError:
     __version__ = "0.0.0"
 
 
-def flush(timeout: float | None = 5.0) -> bool:
+def flush(timeout: float | None = 5.0) -> FlushResult:
     """Drains buffered events through the sink without closing it.
 
     This is the drain for a process that is frozen rather than exited — an AWS Lambda handler
@@ -37,10 +38,12 @@ def flush(timeout: float | None = 5.0) -> bool:
         "the invocation timed out".
 
     Returns:
-      True when the events submitted before this call reached the sink. False if the drain did
-      not complete within the timeout, if the worker has already been shut down or has died, or
-      if a batch was abandoned while this call was outstanding (SPEC-021 FR-001) — so True means
-      the events were delivered, not merely that a drain took place. Events submitted
+      A :class:`FlushResult`. Truthy when the events submitted before this call reached the
+      sink — so a truthy result means they were delivered, not merely that a drain took place.
+      Falsy carries a ``reason`` naming which outcome occurred: ``"timed-out"``, ``"retired"``,
+      ``"thread-died"``, ``"queue-full"`` or ``"abandoned"``. It is falsy rather than ``False``:
+      ``if flush():`` is unchanged, but ``flush() is True`` can no longer hold, which is why the
+      type had to change before ``1.0.0`` rather than after (SPEC-034 FR-007). Events submitted
       concurrently by another thread may or may not be included, since the caller cannot have
       meant those, and a batch lost before the call belongs to :func:`health`.
 
@@ -158,6 +161,8 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
 __all__ = [
     "DEFAULT_SHUTDOWN_TIMEOUT",
     "Config",
+    "ContinueResult",
+    "FlushResult",
     "Health",
     "Sink",
     "SinkDeliveryError",

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

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
@@ -10,6 +12,9 @@ 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
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
 __all__ = [
     "critical",
     "debug",
@@ -100,13 +105,66 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
             _diag.absorbed("echoing to the console", exc)
 
 
-def debug(message: str, *, echo: bool = False, **fields: object) -> None:
+def _merge(fields: Mapping[str, object] | None, kv: dict[str, object]) -> dict[str, object]:
+    """Combines the explicit ``fields=`` mapping with the keyword form.
+
+    ``echo`` and ``message`` were reserved words stolen from the caller's field namespace:
+    ``info("x", echo="incoming payload echoed back")`` dropped a real field *and* turned on an
+    unwanted console line, and ``message=`` raised ``TypeError`` (SPEC-034 FR-004). ``fields=``
+    is the way round all three — including its own name, which is why the escape hatch can
+    express every key including the ones this signature reserves — and the only way to pass a
+    key that is not a Python identifier.
+
+    The keyword form wins a collision. ``fields=`` is the bulk route, usually a mapping built
+    somewhere else; ``**kv`` is what the caller wrote at this call site, and a literal
+    overriding a base is what ``{**base, **overrides}`` already means in the language.
+
+    A ``fields=`` that is not a mapping is **absorbed, not raised**. This helper runs in the
+    emitter, before :func:`_log`, so it sits outside that function's orphan guard entirely: an
+    unguarded ``{**fields, **kv}`` propagated a ``TypeError`` into the application on all four
+    entry paths, including the orphan one where SPEC-025's promise holds today, and inside a span
+    the decorator then recorded ``status=error`` with an ``error.type`` the caller's code never
+    raised. It was also asymmetric in a way neither reading defends — ``fields=[]`` was silently
+    ignored while ``fields=["x"]`` crashed. The library coerces rather than validates (SPEC-017),
+    so the tolerant half is the one that matches, and the fault is announced by type.
+
+    Args:
+      fields: The explicit mapping, or ``None``.
+      kv: The keyword-collected fields.
+
+    Returns:
+      One mapping, with ``kv`` taking precedence. The caller's ``fields`` is never mutated, and a
+        ``fields=`` that could not be merged is dropped rather than costing the event.
+
+    Raises:
+      None.
+    """
+    if not fields:
+        return kv
+    try:
+        return {**fields, **kv}
+    except Exception as exc:
+        _diag.absorbed("merging the fields= argument", exc, "the fields= argument was ignored")
+        return kv
+
+
+def debug(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``DEBUG`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -114,16 +172,26 @@ def debug(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("DEBUG", message, echo, fields)
+    _log("DEBUG", message, echo, _merge(fields, kv))
 
 
-def info(message: str, *, echo: bool = False, **fields: object) -> None:
+def info(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits an ``INFO`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -131,16 +199,26 @@ def info(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("INFO", message, echo, fields)
+    _log("INFO", message, echo, _merge(fields, kv))
 
 
-def warning(message: str, *, echo: bool = False, **fields: object) -> None:
+def warning(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``WARNING`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -148,16 +226,26 @@ def warning(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("WARNING", message, echo, fields)
+    _log("WARNING", message, echo, _merge(fields, kv))
 
 
-def error(message: str, *, echo: bool = False, **fields: object) -> None:
+def error(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits an ``ERROR`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -165,16 +253,26 @@ def error(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("ERROR", message, echo, fields)
+    _log("ERROR", message, echo, _merge(fields, kv))
 
 
-def critical(message: str, *, echo: bool = False, **fields: object) -> None:
+def critical(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``CRITICAL`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -182,4 +280,4 @@ def critical(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("CRITICAL", message, echo, fields)
+    _log("CRITICAL", message, echo, _merge(fields, kv))

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

@@ -7,6 +7,7 @@ import atexit
 import functools
 import threading
 from collections.abc import Callable
+from dataclasses import replace
 from time import monotonic
 from typing import TYPE_CHECKING, Any, TypeVar, cast, overload
 
@@ -20,6 +21,7 @@ from log_foundry.ids import (
     parse_traceparent,
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
+from log_foundry.results import ContinueResult, FlushResult
 from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_SWAP_TIMEOUT, Health, Worker
 
 if TYPE_CHECKING:
@@ -104,7 +106,7 @@ def continue_trace(
     trace_id: str | None = None,
     parent_span_id: str | None = None,
     baggage: str | None = None,
-) -> bool:
+) -> ContinueResult:
     """Adopts an inbound trace context so this process's spans join the caller's trace.
 
     Call it on the first line of the entry point: if a span is already open and it is a root,
@@ -135,31 +137,52 @@ def continue_trace(
         losing the trace join because one field was malformed is worse.
 
     Returns:
-      True when a context was adopted, False when nothing valid was supplied and a fresh
+      A :class:`ContinueResult`. Truthy when a context was adopted; falsy with a ``reason`` of
+      ``"nothing-supplied"`` when no argument carried one, or ``"rejected"`` when something was
+      supplied and was malformed — two outcomes that read identically as ``False`` today, where
+      the second is a caller bug and the first is often a deliberate "continue if there is one".
+      Falsy also means a fresh
       trace is in use. Supplying nothing at all is a silent no-op rather than a rejection,
       since a caller who did not propagate a header would otherwise get a line per
       invocation.
 
+      **The verdict describes the trace context and nothing else.** ``baggage=`` is merged
+      independently of it (SPEC-014: losing correlating fields is bad, and losing the trace join
+      because one field was malformed is worse), so ``continue_trace(baggage=...)`` alone applies
+      the baggage and still reports falsy — there was no trace context to adopt. The reason then
+      distinguishes the two honestly, because ``"rejected"`` means **exactly** that a rejection
+      was announced through ``_diag``: a malformed ``baggage=`` is a rejection, a well-formed one
+      is not, and each reads back the way the stderr line does. A first version keyed the reason
+      on "was any argument supplied", which reported ``"nothing-supplied"`` for a malformed
+      baggage header *while writing the rejection line for it* — the discrimination FR-007 AC-3
+      exists to provide, stated backwards.
+
     Raises:
       None.
     """
     adopted: tuple[str, str | None] | None = None
+    announced = False
     if traceparent is not None:
         if trace_id is not None or parent_span_id is not None:
             _diag.rejected("both traceparent and explicit ids given; traceparent wins", traceparent)
         parsed = parse_traceparent(traceparent)
         if parsed is None:
             _diag.rejected("unparseable traceparent", traceparent)
+            announced = True
         else:
             adopted = parsed
     elif trace_id is not None:
         if not is_valid_trace_id(trace_id):
             _diag.rejected("invalid trace_id", trace_id)
+            announced = True
         elif parent_span_id is not None and not is_valid_span_id(parent_span_id):
             _diag.rejected("invalid parent_span_id; joining as a root", parent_span_id)
             adopted = (trace_id, None)
         else:
             adopted = (trace_id, parent_span_id)
+    elif parent_span_id is not None:
+        _diag.rejected("parent_span_id given with no trace_id to join", parent_span_id)
+        announced = True
 
     if adopted is not None:
         context.set_adopted_context(*adopted)
@@ -169,10 +192,13 @@ def continue_trace(
         parsed_baggage = context.parse_baggage_header(baggage)
         if parsed_baggage is None:
             _diag.rejected("unusable baggage header", baggage)
+            announced = True
         else:
             context.set_baggage(**parsed_baggage)
 
-    return adopted is not None
+    if adopted is not None:
+        return ContinueResult(ok=True)
+    return ContinueResult(ok=False, reason="rejected" if announced else "nothing-supplied")
 
 
 def _reparent_current_span(trace_id: str, parent_span_id: str | None) -> None:
@@ -636,7 +662,7 @@ def _adopt_declined_swap(new_sink: Sink) -> None:
         _orphan_sink = new_sink
 
 
-def _flush_worker(timeout: float | None = 5.0) -> bool:
+def _flush_worker(timeout: float | None = 5.0) -> FlushResult:
     """Drains the process worker without retiring it, backing ``flush()`` (SPEC-013 FR-003).
 
     This deliberately does not call :func:`_get_worker`: a process that never logged has
@@ -647,7 +673,9 @@ def _flush_worker(timeout: float | None = 5.0) -> bool:
       timeout: Seconds to wait for the drain, or ``None`` to wait indefinitely.
 
     Returns:
-      Whether everything outstanding was delivered, and True when no worker exists.
+      A :class:`FlushResult`, truthy when everything outstanding was delivered and when no
+      worker exists — a process that never logged has nothing to drain, so it has lost
+      nothing.
 
     Raises:
       None. A flush is the call most likely to be made in a ``finally``, so the library must
@@ -656,11 +684,11 @@ def _flush_worker(timeout: float | None = 5.0) -> bool:
     """
     worker = _worker
     if worker is None:
-        return True
+        return FlushResult(ok=True)
     try:
         return worker.flush(timeout)
     except Exception:
-        return False
+        return FlushResult(ok=False, reason="thread-died")
 
 
 def _worker_health() -> Health:
@@ -710,7 +738,7 @@ def _worker_health() -> Health:
         )
     health = worker.health()
     if _orphan_retired and not health.retired:
-        return health._replace(retired=True)
+        return replace(health, retired=True)
     return health
 
 

log_foundry-0.10.2.dev45/src/log_foundry/results.py

@@ -0,0 +1,65 @@
+"""Result types for the two public calls that answered five questions with one bit (SPEC-034)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["ContinueResult", "FlushResult"]
+
+
+@dataclass(frozen=True)
+class _Result:
+    """A verdict that reads as a boolean and can say why (SPEC-034 FR-007).
+
+    ``flush()`` returned one bit for five distinct outcomes — timed out, worker retired, drain
+    thread died, queue too full for the marker, a batch abandoned — and a Lambda handler needs
+    "the worker is retired, my code is wrong" separated from "the sink is slow". A ``NamedTuple``
+    cannot be retrofitted here: a non-empty tuple is always truthy, so every ``if flush():``
+    would silently start passing.
+
+    The type exists now, before ``1.0.0``, precisely so that later reasons are additive. It grows
+    by new ``reason`` values and never by changing :meth:`__bool__`.
+
+    Attributes:
+      ok: Whether the operation succeeded, and what ``bool()`` reports.
+      reason: A short stable token naming *why* when it did not, or ``None`` when it did. New
+        tokens may appear in any release; code should branch on ``bool()`` and treat an unknown
+        reason as "some other failure" rather than matching exhaustively.
+    """
+
+    ok: bool
+    reason: str | None = None
+
+    def __bool__(self) -> bool:
+        """Reports the verdict, so every existing ``if flush():`` keeps its meaning.
+
+        Args:
+          None.
+
+        Returns:
+          Whether the operation succeeded.
+
+        Raises:
+          None.
+        """
+        return self.ok
+
+
+@dataclass(frozen=True)
+class FlushResult(_Result):
+    """What :func:`log_foundry.flush` returns.
+
+    ``reason`` is ``None`` on success. The tokens it can carry today are ``"timed-out"``,
+    ``"retired"``, ``"thread-died"``, ``"queue-full"`` and ``"abandoned"``.
+    """
+
+
+@dataclass(frozen=True)
+class ContinueResult(_Result):
+    """What :func:`log_foundry.continue_trace` returns.
+
+    ``reason`` is ``None`` on success. Today it distinguishes ``"nothing-supplied"`` — no
+    argument carried a context — from ``"rejected"``, which means something *was* supplied and
+    was malformed. Those two read identically as ``False``, and the second is a caller bug where
+    the first is often a deliberate "continue if there is one to continue".
+    """

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev45}/src/log_foundry/sinks/base.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 from abc import abstractmethod
-from typing import NamedTuple, Protocol, runtime_checkable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
 
 __all__ = ["Sink", "SinkDeliveryError", "SinkLosses", "read_losses"]
 
@@ -19,7 +20,8 @@ class SinkDeliveryError(Exception):
     """
 
 
-class SinkLosses(NamedTuple):
+@dataclass(frozen=True)
+class SinkLosses:
     """What a sink discarded or could not confirm, cumulative for its lifetime (FR-002).
 
     ``failed`` is an upper bound on loss, not a count of it: a sink that also raises on total

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev45}/src/log_foundry/worker.py

@@ -5,9 +5,11 @@ from __future__ import annotations
 import queue
 import threading
 import time
-from typing import TYPE_CHECKING, NamedTuple, cast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
 
 from log_foundry import _diag, _lifecycle
+from log_foundry.results import FlushResult
 
 if TYPE_CHECKING:
     from log_foundry.sinks.base import Sink, SinkLosses
@@ -57,7 +59,8 @@ def _bounded_seconds(timeout: float | None) -> str:
         return "?"
 
 
-class Health(NamedTuple):
+@dataclass(frozen=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
@@ -112,7 +115,10 @@ class Health(NamedTuple):
         may have been misrouted, never merely that a close was slow — ``closing_sinks`` is the
         field for that.
       closing_sinks: Swapped-out sinks whose ``close()`` is running *at this instant* — a live
-        gauge, not a counter, and the only field here that can fall as well as rise. A close is
+        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
         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
@@ -460,7 +466,7 @@ class Worker:
 
         return read_losses(self.sink)
 
-    def flush(self, timeout: float | None = 5.0) -> bool:
+    def flush(self, timeout: float | None = 5.0) -> FlushResult:
         """Drains everything submitted before this call through the sink, without stopping.
 
         The precise claim is that nothing was abandoned while this call was outstanding: the
@@ -498,32 +504,42 @@ class Worker:
             wait, so the two cannot add up to twice the timeout. ``None`` waits indefinitely.
 
         Returns:
-          True once the worker has delivered them. False on timeout, on a worker already shut
-          down or dead, on a queue too full to accept the marker, and when the drain carrying
-          those events was abandoned after exhausting retries (SPEC-021 FR-001). That last
-          case used to return True, a false success exactly where ``flush()`` matters most.
+          A :class:`FlushResult`, truthy once the worker has delivered them and otherwise
+          falsy with a ``reason``: ``"timed-out"``, ``"retired"``, ``"thread-died"``,
+          ``"queue-full"``, or ``"abandoned"`` when the drain carrying those events gave up
+          after exhausting retries (SPEC-021 FR-001) — that last case used to return True, a
+          false success exactly where ``flush()`` matters most. **The inner call carries the
+          type too, not only the public ``log_foundry.flush``** (SPEC-034 FR-007 AC-1b): the
+          five outcomes are distinguishable only here, so a public wrapper over a bare ``bool``
+          could name none of them without guessing.
 
         Raises:
           None.
         """
         with self._lock:
             if self._shutdown_done:
-                return False
+                return FlushResult(ok=False, reason="retired")
         if not self._thread.is_alive():
-            return False
+            return FlushResult(ok=False, reason="thread-died")
         with self._lock:
             marker = _FlushMarker(self.failed_batches)
         deadline = None if timeout is None else time.monotonic() + timeout
         try:
             self._queue.put(marker, timeout=timeout)
         except queue.Full:
-            return False
+            return FlushResult(ok=False, reason="queue-full")
         if self._drain_finished.is_set() or not self._thread.is_alive():
-            return marker.event.is_set() and marker.delivered
+            answered = marker.event.is_set()
+            delivered = answered and marker.delivered
+            if delivered:
+                return FlushResult(ok=True)
+            return FlushResult(ok=False, reason="abandoned" if answered else "thread-died")
         remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
         if not marker.event.wait(remaining):
-            return False
-        return marker.delivered
+            return FlushResult(ok=False, reason="timed-out")
+        if not marker.delivered:
+            return FlushResult(ok=False, reason="abandoned")
+        return FlushResult(ok=True)
 
     def swap_sink(self, new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) -> bool:
         """Retargets delivery at a new sink, draining and closing the previous one (FR-003).