log-foundry 0.10.2.dev126__tar.gz → 0.10.2.dev127__tar.gz

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev126
+Version: 0.10.2.dev127
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -357,9 +357,14 @@ def handler(): ...
 def process(): ...
 ```
 
-- `name` — override the span name (defaults to the function's `__qualname__`).
+- `name` — override the span name (defaults to the function's `__qualname__`; a callable with
+  none — a `functools.partial`, a callable instance — is named after its type).
 - `defaults` — per-decorator fields merged into every event this span emits.
 
+`@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
+a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
+(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`
 sub-document carrying the exception's type, module, message and formatted stack, then
@@ -415,7 +420,9 @@ def process_payment(user_id: int) -> str:
   [`reset_context()`](#clearing-context-in-a-long-lived-process).
 - **`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.
+  still rides the normal pipeline to the sink — echo never redirects. A console that has gone
+  away for good (a broken pipe, a closed stream) is announced once and echo is switched off for
+  the rest of the process; any other console fault is announced on a throttle.
 - **`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 —

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/README.md

@@ -306,9 +306,14 @@ def handler(): ...
 def process(): ...
 ```
 
-- `name` — override the span name (defaults to the function's `__qualname__`).
+- `name` — override the span name (defaults to the function's `__qualname__`; a callable with
+  none — a `functools.partial`, a callable instance — is named after its type).
 - `defaults` — per-decorator fields merged into every event this span emits.
 
+`@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
+a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
+(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`
 sub-document carrying the exception's type, module, message and formatted stack, then
@@ -364,7 +369,9 @@ def process_payment(user_id: int) -> str:
   [`reset_context()`](#clearing-context-in-a-long-lived-process).
 - **`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.
+  still rides the normal pipeline to the sink — echo never redirects. A console that has gone
+  away for good (a broken pipe, a closed stream) is announced once and echo is switched off for
+  the rest of the process; any other console fault is announced on a throttle.
 - **`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 —

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/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.dev126"
+version = "0.10.2.dev127"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/_diag.py

@@ -22,7 +22,17 @@ from __future__ import annotations
 
 import sys
 
-__all__ = ["absorbed", "errno_of", "lost", "rejected"]
+__all__ = ["WARN_EVERY", "absorbed", "errno_of", "lost", "rejected"]
+
+WARN_EVERY = 1000
+"""The period of every per-event throttle in the library (SPEC-017 FR-005, SPEC-055 FR-005).
+
+A site that can fail once per event writes its line on the first failure and then on every
+``WARN_EVERY``-th, carrying the running total, because a line per failure is its own outage and
+silence is how the failure survives to production. One definition, here, because the worker's
+queue-full and post-shutdown sites and the console writer's stream-fault site all throttle on
+the same period, and two constants stating one number disagree eventually.
+"""
 
 _MAX_DETAIL = 200
 

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/config.py

@@ -88,6 +88,40 @@ def _require_positive(name: str, value: int | None) -> None:
         raise ValueError(f"{name} must be >= 1, got {value}")
 
 
+def _require_text(name: str, value: object) -> str | None:
+    """Rejects a stamp that is not a ``str`` or cannot encode as UTF-8 (SPEC-055 FR-001).
+
+    ``service``, ``version`` and ``env`` are copied from the config into every event without
+    passing through ``sanitize`` — the one route by which a string reaches an event unbounded
+    and uncoerced, which is deliberate on the hottest path in the library. So the check is at
+    the door instead (invariant 13): a lone surrogate here would otherwise cost every batch on
+    every sink that binds ``service`` as a column, for the life of the process, and an ``int``
+    would land in a ``str`` field. What is stored is ``str.__str__(value)``, an exact ``str``,
+    so a ``StrEnum`` member is accepted and a ``str`` subclass instance never reaches an event.
+
+    Args:
+      name: The setting's name, used in the error message.
+      value: The proposed stamp, or ``None`` to skip the check.
+
+    Returns:
+      The stamp as an exact ``str``, or ``None`` when it was not supplied.
+
+    Raises:
+      TypeError: If the value is present and not a ``str``.
+      ValueError: If the value is present and does not encode as UTF-8.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a str, got {type(value).__name__}")
+    plain = str.__str__(value)
+    try:
+        plain.encode("utf-8")
+    except UnicodeEncodeError:
+        raise ValueError(f"{name} must be encodable as UTF-8; it carries a lone surrogate") from None
+    return plain
+
+
 def configure(
     *,
     service: str | None = None,
@@ -104,8 +138,9 @@ def configure(
 
     Only the arguments passed are applied, so repeated calls compose rather than reset. If
     no sink has ever been set, this defaults to :class:`~log_foundry.sinks.stdout.StdoutSink`,
-    the zero-dependency dev default (arch §8). Every ceiling is validated before anything is
-    assigned, so a rejected call leaves the config exactly as it found it.
+    the zero-dependency dev default (arch §8). Every ceiling and every stamp is validated before
+    anything is assigned — and before the sink is stamped into the ownership record — so a
+    rejected call leaves the config and the record exactly as it found them.
 
     A ``sink=`` passed after logging has already started is the one argument that needs more
     than an assignment, because whatever is delivering captured its sink before the call
@@ -161,12 +196,16 @@ def configure(
       None.
 
     Raises:
-      ValueError: If any ceiling is less than 1.
+      ValueError: If any ceiling is less than 1, or a stamp does not encode as UTF-8.
+      TypeError: If ``service``, ``version`` or ``env`` is not a ``str`` (SPEC-055 FR-001).
     """
     _require_positive("max_value_bytes", max_value_bytes)
     _require_positive("max_stack_bytes", max_stack_bytes)
     _require_positive("max_keys", max_keys)
     _require_positive("max_depth", max_depth)
+    service = _require_text("service", service)
+    version = _require_text("version", version)
+    env = _require_text("env", env)
 
     changed: dict[str, object] = {
         name: value

log_foundry-0.10.2.dev127/src/log_foundry/console.py

@@ -0,0 +1,131 @@
+"""Console echo — a synchronous, human-readable output path (SPEC-002 FR-002)."""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import TextIO
+
+from log_foundry import _diag
+
+__all__ = ["ConsoleWriter"]
+
+
+class ConsoleWriter:
+    """Renders events as human-readable ``LEVEL   message`` lines to a stream.
+
+    This is separate from the async :class:`~log_foundry.sinks.base.Sink`: where the sink
+    ships structured JSON downstream, the console writer surfaces a line immediately so an
+    operator sees it without waiting for the async flush. It is deliberately dumb, rendering
+    an already-built event dict and knowing nothing about spans, and echo is additive — an
+    echoed event still rides the normal pipeline to the sink.
+
+    The default stream is **stderr**, not stdout (SPEC-031 FR-003, which corrected two
+    documents that said otherwise). It is the twelve-factor convention ``StderrSink`` already
+    cites — logs on stderr, the application's own output on stdout — so an echo cannot corrupt
+    a program whose stdout is a data stream someone pipes.
+
+    **The writer owns its stream's failures** (SPEC-055 FR-005). ``api._log`` used to absorb
+    them one line at a time: measured, 200,000 echoed events piped into ``head -1`` wrote
+    199,970 identical stderr lines, one per event, forever. A ``BrokenPipeError``, or the
+    ``ValueError`` a closed file raises, is a stream that will not come back, so it is announced
+    once and echo is disabled for the life of the writer. Any other ``Exception`` may be
+    transient — ``EAGAIN`` on a non-blocking terminal, ``ENOSPC`` on a file — so the writer keeps
+    trying and announces the first failure and then every :data:`_diag.WARN_EVERY`-th with the
+    running total, the queue-full site's idiom. The state lives on the writer rather than the
+    module so a ``ConsoleWriter(stream=…)`` built for a test starts clean, and the counter is
+    taken under a lock on the failure path only, since ``_log`` reaches the process-global
+    writer from arbitrary application threads; the disable flag is a set-only latch read
+    unlocked, as ``Worker.submit`` reads ``_shutdown_done``.
+    """
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        """Binds the writer to an output stream, once, at construction.
+
+        The binding is deliberate and permanent for the life of the writer: a later
+        ``contextlib.redirect_stderr`` or a test's capture of ``sys.stderr`` is not honoured,
+        because the attribute was resolved here. ``api._console`` is built at import, so in
+        practice a process's echo stream is fixed before any test runs. Passing ``stream=``
+        explicitly is how a caller — a test above all — captures the output (SPEC-031 FR-003).
+
+        Args:
+          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        self._stream = stream if stream is not None else sys.stderr
+        self._disabled = False
+        self._failures = 0
+        self._lock = threading.Lock()
+
+    def write(self, event: dict[str, object]) -> None:
+        """Writes one ``{level:<7} {message}`` line and flushes immediately.
+
+        A stream fault is absorbed here rather than propagated: a permanent one disables the
+        writer after one announcement, a transient one is counted and announced on the throttle
+        (see the class docstring). The ``KeyError`` for an event missing ``level`` or
+        ``message`` still escapes, because that is a library defect rather than a stream fault,
+        and ``api._log``'s outer guard is the total guard for it.
+
+        Args:
+          event: An already-built event carrying ``level`` and ``message``.
+
+        Returns:
+          None.
+
+        Raises:
+          KeyError: If the event is missing ``level`` or ``message``.
+        """
+        if self._disabled:
+            return
+        level = str(event["level"])
+        message = str(event["message"])
+        try:
+            self._stream.write(f"{level:<7} {message}\n")
+            self._stream.flush()
+        except Exception as exc:
+            if _is_permanent(exc):
+                self._disabled = True
+                _diag.absorbed(
+                    "echoing to the console",
+                    exc,
+                    "echo is disabled for the life of this writer; events still reach the sink",
+                )
+                return
+            with self._lock:
+                self._failures += 1
+                total = self._failures
+            if total == 1 or total % _diag.WARN_EVERY == 0:
+                _diag.absorbed(
+                    "echoing to the console",
+                    exc,
+                    f"{total} echo(es) failed; count is cumulative",
+                )
+
+
+def _is_permanent(exc: Exception) -> bool:
+    """Decides whether a stream fault means the stream will not come back.
+
+    A ``BrokenPipeError`` is a reader that has gone, and the ``ValueError`` a closed file raises
+    is a stream nothing will reopen. ``UnicodeEncodeError`` is *also* a ``ValueError`` and is
+    neither: it is one message a strict-ASCII console could not render, and the next plain
+    message would write fine — measured, a bare ``except ValueError`` latched echo off for the
+    rest of the process on the first ``"café"``. So the ``UnicodeError`` family is excluded and
+    takes the throttle with every other transient fault.
+
+    Args:
+      exc: The exception the stream raised.
+
+    Returns:
+      Whether to disable echo for the life of the writer.
+
+    Raises:
+      None.
+    """
+    if isinstance(exc, BrokenPipeError):
+        return True
+    return isinstance(exc, ValueError) and not isinstance(exc, UnicodeError)

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/decorator.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import functools
+import inspect
 import threading
 from collections.abc import Callable
 from time import monotonic
@@ -628,6 +629,94 @@ def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
     _flush(span)
 
 
+def _refuse_unusable(fn: object) -> None:
+    """Refuses, at decoration, a callable ``@trace`` could not trace (SPEC-055 FR-002).
+
+    Invariant 13: a bad argument is refused where it is written, never on the first call. A
+    ``classmethod`` or ``staticmethod`` object is a decorator applied in the wrong order —
+    ``classmethod`` is not callable, so the wrapper would fail every call, and ``staticmethod``
+    *is* callable but the wrapper replaces the descriptor, so an instance call would hand
+    ``self`` to a function declared without one. A ``str`` is the slip ``@trace("checkout")``,
+    which meant ``name=``. Anything else that is not callable is refused by type.
+
+    Args:
+      fn: Whatever was handed to the decorator.
+
+    Returns:
+      None.
+
+    Raises:
+      TypeError: If ``fn`` is a ``classmethod`` or ``staticmethod`` object, a ``str``, or not
+        callable at all.
+      Exception: Whatever the callable's own attribute access raises — a ``__class__`` property,
+        say — at decoration, in the caller's frame, which is invariant 13's moment.
+    """
+    if isinstance(fn, (classmethod, staticmethod)):
+        kind = type(fn).__name__
+        inner = getattr(fn.__func__, "__qualname__", "the function")
+        raise TypeError(
+            f"@trace cannot wrap the {kind} object around {inner}; put @{kind} above @trace, "
+            f"so that @trace decorates the plain function"
+        )
+    if isinstance(fn, str):
+        raise TypeError(
+            f"@trace needs a callable, got str; pass a span name as @trace(name={fn!r})"
+        )
+    if not callable(fn):
+        raise TypeError(f"@trace needs a callable, got {type(fn).__name__}")
+
+
+def _span_name(fn: object) -> str:
+    """Resolves the span name once, at decoration, from any callable (SPEC-055 FR-002).
+
+    ``fn.__qualname__`` where the callable has one, else its type's name — so a
+    ``functools.partial`` traces as ``partial`` and a callable instance as its class, where
+    reading the attribute per call inside the wrapper raised ``AttributeError`` into the
+    application on every call. A ``__qualname__`` that exists but is not a ``str`` needs no
+    clause: ``functools.wraps`` copies it onto the wrapper and Python refuses a non-``str``
+    there before any wrapper exists.
+
+    Args:
+      fn: The callable being decorated.
+
+    Returns:
+      The span name.
+
+    Raises:
+      Exception: Whatever the callable's own ``__qualname__`` lookup raises other than
+        ``AttributeError``, at decoration, in the caller's frame.
+    """
+    qualname = getattr(fn, "__qualname__", None)
+    return qualname if isinstance(qualname, str) else type(fn).__name__
+
+
+def _is_async(fn: object) -> bool:
+    """Decides the async wrapper, consulting a callable instance's ``__call__`` (SPEC-055 FR-002).
+
+    ``asyncio.iscoroutinefunction`` sees through a ``functools.partial`` but reads a callable
+    instance whose ``__call__`` is ``async def`` as synchronous, so accepting instances at all
+    (FR-002) would have handed one the sync wrapper and closed the span before the coroutine
+    ran — the generator finding's shape again. The type's ``__call__`` is asked too, for
+    anything that is not a plain function; a ``partial``'s or a class's is a slot wrapper and
+    reads as synchronous, which is correct.
+
+    Args:
+      fn: The callable being decorated.
+
+    Returns:
+      Whether the async wrapper applies.
+
+    Raises:
+      Exception: Whatever the callable's own ``__class__`` or ``__call__`` lookup raises, at
+        decoration, in the caller's frame.
+    """
+    if asyncio.iscoroutinefunction(fn):
+        return True
+    if inspect.isfunction(fn):
+        return False
+    return asyncio.iscoroutinefunction(type(fn).__call__)
+
+
 @overload
 def trace(func: F) -> F: ...
 @overload
@@ -646,7 +735,9 @@ def trace(
 
     Args:
       func: The function being decorated when used bare, otherwise ``None``.
-      name: Overrides the span name, which defaults to ``func.__qualname__``.
+      name: Overrides the span name, which defaults to ``func.__qualname__`` where the callable
+        has one and to its type's name otherwise — ``partial`` for a ``functools.partial``, the
+        class name for a callable instance (SPEC-055 FR-002).
       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
@@ -657,18 +748,21 @@ def trace(
       The wrapped function, or a decorator when called with arguments.
 
     Raises:
-      None.
+      TypeError: At decoration, for a ``classmethod`` or ``staticmethod`` object (the decorators
+        are in the wrong order), a ``str`` (``name=`` was meant), anything not callable, or a
+        ``name=`` that is not a ``str`` (SPEC-055 FR-002, invariant 13).
     """
     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.
 
-        :func:`asyncio.iscoroutinefunction` makes the choice once. The two wrappers are
+        :func:`_is_async` makes the choice once. The two wrappers are
         deliberate near-duplicates — the only difference is ``await fn(...)`` — because the
         sync/async split is a hard boundary, and ``contextvars`` already propagates the span
         stack and baggage across ``await`` points and concurrent tasks (arch §5), so the async
-        span opens when the coroutine actually runs and closes when it finishes.
+        span opens when the coroutine actually runs and closes when it finishes. The span name
+        is resolved here, once, rather than read from ``fn`` on every call (SPEC-055 FR-002).
 
         Args:
           fn: The function to wrap.
@@ -677,9 +771,13 @@ def trace(
           The wrapper, typed as the original function.
 
         Raises:
-          None.
+          TypeError: From :func:`_refuse_unusable`, at decoration.
         """
-        if asyncio.iscoroutinefunction(fn):
+        _refuse_unusable(fn)
+        if name is not None and not isinstance(name, str):
+            raise TypeError(f"@trace name= must be a str, got {type(name).__name__}")
+        span_name = name or _span_name(fn)
+        if _is_async(fn):
 
             @functools.wraps(fn)
             async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -704,7 +802,7 @@ def trace(
                 Raises:
                   BaseException: Whatever the wrapped coroutine raises, unchanged.
                 """
-                span, token, scope = _begin(name or fn.__qualname__, span_defaults)
+                span, token, scope = _begin(span_name, span_defaults)
                 status, error = "ok", None
                 try:
                     result = await fn(*args, **kwargs)
@@ -740,7 +838,7 @@ def trace(
             Raises:
               BaseException: Whatever the wrapped function raises, unchanged.
             """
-            span, token, scope = _begin(name or fn.__qualname__, span_defaults)
+            span, token, scope = _begin(span_name, span_defaults)
             status, error = "ok", None
             try:
                 result = fn(*args, **kwargs)

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/sanitize.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import sys
 from collections.abc import Iterable, Mapping, Sequence
 from datetime import date, datetime, time
@@ -40,6 +41,27 @@ The same reasoning as :data:`_INT_LT` beside it, and as ``_placeholder``'s refus
 ``repr()``: what the library writes about a value must be computed by the library.
 """
 
+_STR_STR = str.__str__
+"""``str.__str__``, unbound, so a ``str`` subclass cannot divert the measurement (SPEC-055 FR-001).
+
+On an exact ``str`` it is the identity, so the hot path pays nothing; on a subclass it returns a
+plain copy without consulting the subclass's own ``__str__`` or ``encode``. Measured before it:
+``info(BadEncode("x"))``, where ``encode`` raises, cost the event — absorbed and announced, but
+lost — because ``truncate_str`` called the value's own ``encode`` to measure it. The same
+reasoning as :data:`_INT_LT` and :data:`_FLOAT_REPR`: what the library measures about a value
+must be computed by the library.
+"""
+
+_SURROGATES = re.compile("[\ud800-\udfff]")
+_REPLACEMENT = "\ufffd"
+"""One U+FFFD per lone surrogate, which neither built-in error handler gives (SPEC-055 FR-001).
+
+``errors="replace"`` on an *encode* writes ``?`` and loses the byte; a ``surrogatepass`` encode
+followed by a ``replace`` decode writes three U+FFFD for one surrogate, because the decoder
+rejects each of the three bytes separately. The substitution runs only after a strict encode has
+already failed, so the common case never reaches it.
+"""
+
 _PLAIN_SCALARS: frozenset[type] = frozenset({int, bool})
 
 _TEXTLIKE: tuple[type, ...] = (str, bytes, bytearray, memoryview)
@@ -69,25 +91,38 @@ def _int_digit_ceiling(max_value_bytes: int) -> int:
     return max_value_bytes if limit <= 0 else min(max_value_bytes, limit)
 
 
-def _measured(value: str) -> bytes:
-    """Returns the UTF-8 bytes of a string, tolerating lone surrogates.
+def _measured(value: str) -> tuple[str, bytes, bool]:
+    """Returns a string as an exact ``str`` that encodes strictly, its bytes, and whether it changed.
+
+    A string carrying an unpaired surrogate — anything that went through ``surrogateescape``,
+    such as ``os.fsdecode`` of an undecodable filename — raises ``UnicodeEncodeError`` on a bare
+    ``.encode("utf-8")``. Before SPEC-055 this tolerated that with ``errors="replace"`` to
+    *measure* the string and then returned the caller's string unchanged, so the surrogate left
+    assembly intact: the JSON sinks escaped it, and every sink that hands a raw ``str`` to a
+    driver — ``SQLiteSink``'s ``function`` column above all — raised on it and cost the whole
+    batch its innocent neighbours. Invariant 8 says every string in the event encodes as UTF-8,
+    so the replaced string is what is returned now, and the flag reports the substitution.
 
-    A string carrying an unpaired surrogate — anything that went through
-    ``surrogateescape``, such as ``os.fsdecode`` of an undecodable filename — raises
-    ``UnicodeEncodeError`` on a bare ``.encode("utf-8")``, inside a module contracted never to
-    raise. ``errors="replace"`` is the same tolerance ``context`` applies when measuring an
-    inbound baggage header.
+    The strict encode is tried first, because it is the common case and the C-level fast path;
+    the regex runs only after it has failed. The value is first passed through
+    :data:`_STR_STR`, so what is measured, and what is returned, is always an exact ``str``.
 
     Args:
       value: The string to measure.
 
     Returns:
-      The encoded bytes.
+      The exact ``str`` as measured, its strict UTF-8 bytes, and ``True`` when a surrogate was
+      replaced.
 
     Raises:
       None.
     """
-    return value.encode("utf-8", errors="replace")
+    plain = _STR_STR(value)
+    try:
+        return plain, plain.encode("utf-8"), False
+    except UnicodeEncodeError:
+        clean = _SURROGATES.sub(_REPLACEMENT, plain)
+        return clean, clean.encode("utf-8"), True
 
 
 def truncate_str(value: str, max_bytes: int) -> tuple[str, bool]:
@@ -99,19 +134,25 @@ def truncate_str(value: str, max_bytes: int) -> tuple[str, bool]:
     mid-sequence; where there is no room for anything but the marker, a marker alone is still
     the honest answer.
 
+    The result is an exact ``str`` that encodes as UTF-8 strictly, never the caller's own object
+    (SPEC-055 FR-001): a lone surrogate is replaced by U+FFFD before the measurement, and the
+    flag is therefore "the string was altered" rather than only "the ceiling fired" — a
+    substitution nobody can see is a silent change to the data, which is the rule
+    :meth:`_Coercer.real` already applies to a non-finite float.
+
     Args:
       value: The string to clip.
       max_bytes: The ceiling, in UTF-8 bytes.
 
     Returns:
-      The clipped string and whether the ceiling fired.
+      The clipped string and whether it was altered — clipped, or a surrogate replaced.
 
     Raises:
       None.
     """
-    raw = _measured(value)
+    plain, raw, replaced = _measured(value)
     if len(raw) <= max_bytes:
-        return value, False
+        return plain, replaced
     budget = max_bytes - _MARKER_BYTES
     if budget <= 0:
         return TRUNCATION_MARKER, True
@@ -125,21 +166,22 @@ def truncate_tail(value: str, max_bytes: int) -> tuple[str, bool]:
     message and the innermost frames last, so the head of an over-long traceback is the least
     useful part of it. The zero-budget guard is not merely defensive — ``raw[-budget:]`` would
     return the whole string at a budget of zero, and ``max_stack_bytes`` may legally be smaller
-    than the marker.
+    than the marker. The result is an exact, strictly encodable ``str`` on the same terms as
+    :func:`truncate_str`.
 
     Args:
       value: The string to clip.
       max_bytes: The ceiling, in UTF-8 bytes.
 
     Returns:
-      The clipped string and whether the ceiling fired.
+      The clipped string and whether it was altered — clipped, or a surrogate replaced.
 
     Raises:
       None.
     """
-    raw = _measured(value)
+    plain, raw, replaced = _measured(value)
     if len(raw) <= max_bytes:
-        return value, False
+        return plain, replaced
     budget = max_bytes - _MARKER_BYTES
     if budget <= 0:
         return TRUNCATION_MARKER, True
@@ -269,9 +311,9 @@ class _Coercer:
         if isinstance(value, Decimal):
             return self.text(str(value))
         if isinstance(value, (bytes, bytearray, memoryview)):
-            return self.text(bytes(value).decode("utf-8", errors="replace"))
+            return self.text(self._decoded(bytes(value)))
         if isinstance(value, str):
-            return self.text(str(value))
+            return self.text(value)
         if isinstance(value, Mapping):
             return self.mapping(value, depth)
         if isinstance(value, (set, frozenset)):
@@ -280,6 +322,30 @@ class _Coercer:
             return self.members(value, depth)
         return self._placeholder(value)
 
+    def _decoded(self, value: bytes) -> str:
+        """Decodes bytes as UTF-8, replacing what does not decode and recording that it did.
+
+        Strict first, and only on ``UnicodeDecodeError`` with ``errors="replace"`` (SPEC-055
+        FR-001): before this the replacement was unconditional and silent, so the same
+        undecodable byte was marked when it arrived as a ``str`` and unmarked when it arrived as
+        ``bytes``. The rule is the one every other substitution here follows — a change nobody
+        can see is a change that sets ``truncated``.
+
+        Args:
+          value: The bytes to decode.
+
+        Returns:
+          The decoded text, with U+FFFD where a byte sequence was not UTF-8.
+
+        Raises:
+          None.
+        """
+        try:
+            return value.decode("utf-8")
+        except UnicodeDecodeError:
+            self.truncated = True
+            return value.decode("utf-8", errors="replace")
+
     def mapping(self, value: Mapping[Any, object], depth: int) -> object:
         """Coerces a mapping, capping it at ``max_keys`` and guarding against a cycle.
 
@@ -341,12 +407,46 @@ class _Coercer:
             self._parents.pop()
 
     def key(self, key: object) -> str:
-        """Coerces a mapping key to a bounded string, since JSON object keys are always strings.
+        """Coerces a mapping key to a bounded string, and is total (SPEC-055 FR-004).
+
+        Whatever the key's own ``__str__``, ``bit_length`` or ``__lt__`` raises is caught here
+        rather than in :meth:`value`, whose guard sits around the *enclosing* mapping: measured,
+        ``{"sib": 1, KeyBoom(): 2}`` reached the sink as ``<unserializable: dict>`` with
+        ``truncated`` unset, so one hostile key took every sibling with it — the exact outcome
+        the integer branch below was written to prevent for one kind of key. The key becomes a
+        ``<unserializable key: T>`` placeholder naming its type, on :meth:`_placeholder`'s
+        no-``repr`` rule, and ``truncated`` is set: a value placeholder is visible on its own,
+        but a key that could not be rendered is a substitution the reader must be told about.
+
+        Two hostile keys of one type collide on one placeholder and the later wins, which is
+        accepted: the alternative is a placeholder carrying something of the key's identity,
+        which is what arch §6 forbids, and the collision is still marked because each replaced
+        key sets ``truncated``. The guard is here rather than in :meth:`mapping`'s loop because
+        the loop's other two failures — the ``max_keys`` cap and a value that cannot be coerced
+        — already have owners, and a third ``try`` around the loop would hide which one fired.
+
+        Args:
+          key: The mapping key, of any type.
+
+        Returns:
+          The bounded string form of the key, or the key placeholder.
+
+        Raises:
+          None.
+        """
+        try:
+            return self._key(key)
+        except Exception:
+            self.truncated = True
+            return self.text(f"<unserializable key: {_type_name(key)}>")
+
+    def _key(self, key: object) -> str:
+        """Renders one mapping key, since JSON object keys are always strings.
 
         An integer key goes through :meth:`integer` first. A bare ``str()`` here would raise on
         an over-long one — the very ``ValueError`` this module exists to keep away from a sink
-        — and the failure would be caught up in :meth:`value`, replacing the whole mapping with
-        a placeholder, so one hostile key would take every sibling with it, unmarked. ``bool``
+        — and the failure would be caught up in :meth:`key`, replacing the key with a
+        placeholder where its digits would have done. ``bool``
         is excluded because ``True`` must render as the key ``"True"``, not ``"1"``.
 
         A float key goes through :meth:`real` for the same reason, and its ``text()`` wrap is
@@ -362,7 +462,7 @@ class _Coercer:
           The bounded string form of the key.
 
         Raises:
-          Exception: Whatever the key's own ``__str__`` raises; :meth:`value` is the guard.
+          Exception: Whatever the key's own ``__str__`` raises; :meth:`key` is the guard.
         """
         if isinstance(key, str):
             return self.text(key)
@@ -458,7 +558,9 @@ class _Coercer:
         A type name rather than ``repr(value)`` on purpose: arch §6 refuses to auto-capture
         argument and return values so the library cannot leak secrets or PII, and ``repr()`` of
         an arbitrary object routinely prints attribute values — a credential held on a client
-        object would land in the log.
+        object would land in the log. The placeholder goes through :meth:`text` like any other
+        string (SPEC-055 FR-004): ``type.__name__`` is writable, so a type named with more than
+        ``max_value_bytes`` would otherwise be the one string in the event no ceiling reached.
 
         Args:
           value: The value that could not be coerced.
@@ -469,11 +571,28 @@ class _Coercer:
         Raises:
           None. A pathological metaclass is still not this module's problem.
         """
-        try:
-            name = type(value).__name__
-        except Exception:
-            name = "?"
-        return f"<unserializable: {name}>"
+        return self.text(f"<unserializable: {_type_name(value)}>")
+
+
+def _type_name(value: object) -> str:
+    """Returns a value's type name, or ``"?"`` when even that cannot be read.
+
+    Shared by both placeholders so the no-``repr`` rule has one implementation. A metaclass
+    whose ``__name__`` is a raising property is the case the fallback exists for.
+
+    Args:
+      value: The value whose type is named.
+
+    Returns:
+      The type's ``__name__``, or ``"?"``.
+
+    Raises:
+      None.
+    """
+    try:
+        return str(type(value).__name__)
+    except Exception:
+        return "?"
 
 
 def coerce(value: object, *, cfg: Config) -> object:

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/sinks/kinesis.py

@@ -288,11 +288,13 @@ MAX_PARTITION_KEY_BYTES = 256
 def _partition_key(raw: str) -> str:
     """Bounds a partition key to the service's 256 **bytes**, never 256 characters.
 
-    Both encodes carry an ``errors=`` and both are load-bearing. ``sanitize.coerce`` passes a lone
-    surrogate through unchanged, so a bare ``encode("utf-8")`` on a caller's ``trace_id`` raises
-    ``UnicodeEncodeError`` — a raw exception out of ``emit``, which is the failure SPEC-048 exists
-    to remove rather than introduce. ``errors="ignore"`` on the decode drops a character the byte
-    cut landed inside, so the result always decodes cleanly.
+    Both encodes carry an ``errors=`` and both are load-bearing. Assembly replaces a lone
+    surrogate since SPEC-055 FR-001, so an event field cannot carry one — but this key is derived
+    from whatever field the caller named, on a batch a ``TransformSink`` or a caller's own
+    ``Sink`` may have rewritten after assembly, and a bare ``encode("utf-8")`` on a surrogate
+    raises ``UnicodeEncodeError`` — a raw exception out of ``emit``, which is the failure SPEC-048
+    exists to remove rather than introduce. ``errors="ignore"`` on the decode drops a character
+    the byte cut landed inside, so the result always decodes cleanly.
 
     ``sanitize.truncate_str`` is the inventoried byte-bounded clipper and is deliberately **not**
     reused: it appends a truncation marker, and a marker inside a partition key changes the shard

{log_foundry-0.10.2.dev126 → log_foundry-0.10.2.dev127}/src/log_foundry/worker.py

@@ -27,7 +27,6 @@ module at module scope. Re-exported rather than relocated outright so that
 SPEC-034 froze — keeps naming the same object.
 """
 
-_DROP_WARN_EVERY = 1000
 
 _PUT_POLL_SECONDS = 0.05
 """How long a full-queue ``flush()`` waits before re-asking whether the drain was abandoned.
@@ -567,7 +566,7 @@ class Worker:
             with self._lock:
                 self.dropped += 1
                 total = self.dropped
-            if total == 1 or total % _DROP_WARN_EVERY == 0:
+            if total == 1 or total % _diag.WARN_EVERY == 0:
                 _diag.lost("submission", total, "log queue full; count is cumulative")
             return
         if not retired and self._shutdown_done:
@@ -594,7 +593,7 @@ class Worker:
         with self._lock:
             self.submitted_after_shutdown += 1
             total = self.submitted_after_shutdown
-        if total == 1 or total % _DROP_WARN_EVERY == 0:
+        if total == 1 or total % _diag.WARN_EVERY == 0:
             _diag.lost(
                 "submission",
                 total,

log_foundry-0.10.2.dev126/src/log_foundry/console.py

@@ -1,61 +0,0 @@
-"""Console echo — a synchronous, human-readable output path (SPEC-002 FR-002)."""
-
-from __future__ import annotations
-
-import sys
-from typing import TextIO
-
-__all__ = ["ConsoleWriter"]
-
-
-class ConsoleWriter:
-    """Renders events as human-readable ``LEVEL   message`` lines to a stream.
-
-    This is separate from the async :class:`~log_foundry.sinks.base.Sink`: where the sink
-    ships structured JSON downstream, the console writer surfaces a line immediately so an
-    operator sees it without waiting for the async flush. It is deliberately dumb, rendering
-    an already-built event dict and knowing nothing about spans, and echo is additive — an
-    echoed event still rides the normal pipeline to the sink.
-
-    The default stream is **stderr**, not stdout (SPEC-031 FR-003, which corrected two
-    documents that said otherwise). It is the twelve-factor convention ``StderrSink`` already
-    cites — logs on stderr, the application's own output on stdout — so an echo cannot corrupt
-    a program whose stdout is a data stream someone pipes.
-    """
-
-    def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the writer to an output stream, once, at construction.
-
-        The binding is deliberate and permanent for the life of the writer: a later
-        ``contextlib.redirect_stderr`` or a test's capture of ``sys.stderr`` is not honoured,
-        because the attribute was resolved here. ``api._console`` is built at import, so in
-        practice a process's echo stream is fixed before any test runs. Passing ``stream=``
-        explicitly is how a caller — a test above all — captures the output (SPEC-031 FR-003).
-
-        Args:
-          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now.
-
-        Returns:
-          None.
-
-        Raises:
-          None.
-        """
-        self._stream = stream if stream is not None else sys.stderr
-
-    def write(self, event: dict[str, object]) -> None:
-        """Writes one ``{level:<7} {message}`` line and flushes immediately.
-
-        Args:
-          event: An already-built event carrying ``level`` and ``message``.
-
-        Returns:
-          None.
-
-        Raises:
-          KeyError: If the event is missing ``level`` or ``message``.
-        """
-        level = str(event["level"])
-        message = str(event["message"])
-        self._stream.write(f"{level:<7} {message}\n")
-        self._stream.flush()