narrativetrace 0.4.2__tar.gz → 0.5.0__tar.gz

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/LICENSE

@@ -7,7 +7,7 @@ Parameters
 
 Licensor:             Empower Agile
 
-Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.4.2. The Licensed Work is (c) 2026 Empower Agile.
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.5.0. The Licensed Work is (c) 2026 Empower Agile.
 
 Additional Use Grant: You may make production use of the Licensed Work for any
                       purpose, including internal use and use in products and
@@ -18,7 +18,7 @@ Additional Use Grant: You may make production use of the Licensed Work for any
                       parties as a logging, tracing, or code-narrative product
                       or service.
 
-Change Date:          Four years from the date the Licensed Work is published. (2030-10-20 for this version)
+Change Date:          Four years from the date the Licensed Work is published. (2030-10-24 for this version)
 
 Change License:       Apache License, Version 2.0
 

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace
-Version: 0.4.2
+Version: 0.5.0
 Summary: Narrative execution tracing for Python — human- and LLM-readable traces
 Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
 Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace"
-version = "0.4.2"
+version = "0.5.0"
 description = "Narrative execution tracing for Python — human- and LLM-readable traces"
 readme = "README.md"
 requires-python = ">=3.12"

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/__init__.py

@@ -97,7 +97,7 @@ from narrativetrace.values import (
     StringVal,
 )
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
 __all__ = [
     "NOOP_CONTEXT",

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/canonical.py

@@ -20,6 +20,7 @@ import time
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime
 
+from narrativetrace import exception_message
 from narrativetrace.concurrency import ThreadIdentity
 from narrativetrace.events import (
     EnterEvent,
@@ -252,7 +253,7 @@ def _split_span_name(span_name: str | None) -> tuple[str, str]:
 
 def _exit_message(span: SpanContext, outcome: TraceOutcome) -> str:
     if isinstance(outcome, Threw):
-        return f"!! {type(outcome.exception).__name__}: {outcome.exception}"
+        return f"!! {type(outcome.exception).__name__}: {exception_message.text(outcome.exception)}"
     name = span.span_name if span.span_name is not None else "method"
     if isinstance(outcome, Returned) and outcome.rendered_value is not None:
         return f"← {name} returned {outcome.rendered_value}"
@@ -286,7 +287,7 @@ def _from_exit_event(event: ExitEvent, anchor: MonotonicAnchor) -> CanonicalEntr
         nt_outcome=_exit_outcome(outcome),
         nt_return_value=returned.rendered_value if returned is not None else None,
         exception_type=type(threw.exception).__name__ if threw is not None else None,
-        exception_message=str(threw.exception) if threw is not None else None,
+        exception_message=exception_message.of(threw.exception) if threw is not None else None,
         nt_exception_package=_package_of(threw.exception) if threw is not None else None,
     )
     return _with_correlation(entry, span)

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/context.py

@@ -227,7 +227,7 @@ class NarrativeContext(ABC):
         self,
         trace_id: TraceId,
         remote_parent_span_id: SpanId | None = None,
-        trace_flags: int = 0,
+        trace_flags: int | None = None,
     ) -> None:
         """Adopts an inbound (e.g. W3C ``traceparent``) trace id for the current scope.
 
@@ -236,7 +236,9 @@ class NarrativeContext(ABC):
         ``parent_span_id``, so a consumer that follows parent ids links this service's trace to the
         caller's; it never appears as a span in this scope's own tree. ``trace_flags`` is the
         ``traceparent`` flags byte (bit 0 = sampled); every span this scope creates carries it as
-        :attr:`~narrativetrace.span.SpanContext.trace_flags`.
+        :attr:`~narrativetrace.span.SpanContext.trace_flags`. ``None`` (the default, a bare id with
+        no ``traceparent``) keeps the scope's current flags, sampled unless a flags byte was adopted
+        earlier; only an explicit value overwrites them.
         """
 
     def story_id(self) -> str | None:
@@ -276,6 +278,9 @@ class _RequestMetadata:
 
 _EMPTY_METADATA = _RequestMetadata()
 
+# W3C trace-flags bit 0. A fresh root is sampled; only an adopted ``traceparent`` overwrites it.
+_SAMPLED = 1
+
 MAX_ADOPTED_SPANS = 10_000
 """Ceiling on spans one stack accepts from worker scopes, and on its live-child registrations.
 
@@ -304,7 +309,7 @@ class _TraceStack:
     scoped_parent: SpanId | None = None
     snapshot_parent: SpanId | None = None
     remote_parent: SpanId | None = None
-    trace_flags: int = 0
+    trace_flags: int = _SAMPLED
     story_id: str | None = None
     chapter_id: str | None = None
     metadata: _RequestMetadata = _EMPTY_METADATA
@@ -773,12 +778,13 @@ class ContextVarNarrativeContext(NarrativeContext):
         self,
         trace_id: TraceId,
         remote_parent_span_id: SpanId | None = None,
-        trace_flags: int = 0,
+        trace_flags: int | None = None,
     ) -> None:
         stack = self._get_stack()
         stack.trace_id = trace_id
         stack.remote_parent = remote_parent_span_id
-        stack.trace_flags = trace_flags
+        if trace_flags is not None:
+            stack.trace_flags = trace_flags
 
     def story_id(self) -> str | None:
         return self._get_stack().story_id
@@ -788,13 +794,13 @@ class ContextVarNarrativeContext(NarrativeContext):
 
     # -- concurrency lifecycle --------------------------------------------- #
     def on_fork_created(self, group_id: str) -> None:
-        self._store.add(ForkCreatedEvent(group_id, _now_nanos()))
+        self._store.add(ForkCreatedEvent(group_id, _now_nanos(), self.current_span_id()))
 
     def on_merge(self, group_id: str, members: list[TraceNode]) -> None:
-        self._store.add(MergeEvent(group_id, len(members), _now_nanos()))
+        self._store.add(MergeEvent(group_id, len(members), _now_nanos(), self.current_span_id()))
 
     def on_fire_and_forget_launched(self, group_id: str) -> None:
-        self._store.add(FireAndForgetEvent(group_id, _now_nanos()))
+        self._store.add(FireAndForgetEvent(group_id, _now_nanos(), self.current_span_id()))
 
     def emit_trace_node(self, node: TraceNode, parent_span_id: SpanId | None) -> None:
         self._emit_trace_node(node, parent_span_id, TreeWalk())

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/events.py

@@ -53,31 +53,53 @@ class ExitEvent(TraceEvent):
 
 @dataclass(frozen=True, slots=True)
 class ForkCreatedEvent(TraceEvent):
-    """Lifecycle marker: a fork group was created."""
+    """Lifecycle marker: a fork group was created.
+
+    ``owner_span_id`` is the span current on the launching thread when the group was created
+    (B-166); ``None`` for a group created outside every span, which no request ever removes.
+    """
 
     group_id: str
     timestamp_nanos: int
+    owner_span_id: SpanId | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class MergeEvent(TraceEvent):
-    """Lifecycle marker: a fork group merged its collected children."""
+    """Lifecycle marker: a fork group merged its collected children.
+
+    ``owner_span_id`` is the span current on the merging (launching) thread (B-166); ``None``
+    outside every span.
+    """
 
     group_id: str
     member_count: int
     timestamp_nanos: int
+    owner_span_id: SpanId | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class FireAndForgetEvent(TraceEvent):
-    """Lifecycle marker: a fire-and-forget group was launched."""
+    """Lifecycle marker: a fire-and-forget group was launched.
+
+    ``owner_span_id`` is the span current on the launching thread (B-166); ``None`` for a group
+    launched outside every span.
+    """
 
     group_id: str
     timestamp_nanos: int
+    owner_span_id: SpanId | None = None
 
 
 def span_id_of(event: TraceEvent) -> SpanId | None:
-    """Returns the span id an event belongs to, or ``None`` for group lifecycle events."""
+    """Returns the span id an event belongs to.
+
+    Enter/exit events answer their own span; group lifecycle events answer the span that
+    launched the group (``owner_span_id``), so a request's cleanup removes them with it. A group
+    created outside every span has no owner: ``None``, and the event is retained (B-166).
+    """
     if isinstance(event, EnterEvent | ExitEvent):
         return event.span_context.span_id
+    if isinstance(event, ForkCreatedEvent | MergeEvent | FireAndForgetEvent):
+        return event.owner_span_id
     return None

narrativetrace-0.5.0/src/narrativetrace/exception_message.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Licensed under the Business Source License 1.1 (see LICENSE); Change Date: four
+# years from publication; Change License: Apache-2.0
+# Copyright (c) 2026 Empower Agile
+"""The one reading of an exception's message every emitter shares (B-174).
+
+``Threw`` holds the live exception, unlike ``Returned``, which
+holds text the value renderer already rendered, so a message never passed the redaction policy:
+``ValueError("bad token: eyJ...")`` reached every output in full while the identical string as a
+parameter answered ``[REDACTED]``. Every renderer, exporter and listener reads the message here.
+
+**@llmNote** Only the value-shape axis applies: a JWT, a Luhn-valid card number or a
+``Set-Cookie`` string inside a message is never legitimate. The name deny-list has nothing to match
+on, and blanking messages by keyword would destroy the diagnostic value the message exists for.
+Length is deliberately not capped.
+
+**@sideEffects** ``str(exc)`` is application code run once per emitter; a rogue ``__str__`` that
+raises degrades to ``<error>`` instead of failing the emitter.
+"""
+
+from __future__ import annotations
+
+from narrativetrace.escape import control_sanitize
+from narrativetrace.redaction import REDACTED_MARKER, RedactionPolicy
+
+UNREADABLE = "<error>"
+
+
+def of(exception: BaseException | None) -> str | None:
+    """The message an emitter may print: replaced whole by the redaction marker when its bytes are
+    a credential, control-escaped always; ``None`` for no exception, ``<error>`` when unreadable."""
+    if exception is None:
+        return None
+    try:
+        raw = str(exception)
+    except Exception:
+        return UNREADABLE
+    if RedactionPolicy.DEFAULT.should_redact_value(raw):
+        return REDACTED_MARKER
+    return control_sanitize(raw)
+
+
+def text(exception: BaseException | None) -> str:
+    """:func:`of` where text rather than ``None`` is needed: ``null`` for no exception."""
+    message = of(exception)
+    return "null" if message is None else message

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/export.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import json
 from typing import Any
 
+from narrativetrace import exception_message
 from narrativetrace.concurrency import ConcurrencyInfo
 from narrativetrace.identity import resolve_identity
 from narrativetrace.nodes import TraceNode
@@ -151,7 +152,7 @@ def _append_outcome(event: dict[str, Any], outcome: TraceOutcome | None) -> None
     elif isinstance(outcome, Threw):
         event["outcome"] = "threw"
         event["errorType"] = type(outcome.exception).__name__
-        event["errorMessage"] = str(outcome.exception)
+        event["errorMessage"] = exception_message.of(outcome.exception)
     elif isinstance(outcome, Incomplete):
         event["outcome"] = "incomplete"
     else:

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/logging_bridge.py

@@ -44,6 +44,7 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from enum import Enum
 
+from narrativetrace import exception_message
 from narrativetrace.context import ContextVarNarrativeContext
 from narrativetrace.escape import control_sanitize
 from narrativetrace.events import (
@@ -254,7 +255,7 @@ class LoggingTraceConsumer:
         self, exception: BaseException, error_context: str | None, keys: dict[str, str]
     ) -> None:
         exc_type = type(exception).__name__
-        message = control_sanitize(str(exception))
+        message = exception_message.text(exception)
         if error_context is not None:
             self._logger.log(
                 self._exception,

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/pipeline/perishable.py

@@ -16,6 +16,7 @@ pinned .NET/TS semantics and is the more predictable contract.
 
 from __future__ import annotations
 
+import threading
 import time
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -23,14 +24,25 @@ from dataclasses import dataclass
 _DEFAULT_CLOCK = time.monotonic
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, eq=False)
 class _TimedEntry[V]:
+    """Compared by identity: a replacement entry never equals the one it replaced."""
+
     value: V
     created: float
 
 
 class PerishableMap[K, V]:
-    """A capacity- and TTL-bounded map with an eviction callback."""
+    """A capacity- and TTL-bounded map with an eviction callback.
+
+    Thread-safe (B-169): an :class:`~threading.RLock` guards every read-modify-write, because the
+    OTel listener puts and removes on caller threads. A sweep removes exactly the entry it
+    examined (by identity), so a replacement put under an expired key is never evicted in its
+    place, and an entry is called back only when its own removal won -- never twice. Callbacks run
+    *after* the lock is released (collect under the lock, release, then call): a callback that
+    re-enters the map cannot deadlock and never observes a half-finished sweep. By then every
+    evicted entry is already out of the map, so a callback's ``remove`` of one answers ``None``.
+    """
 
     def __init__(
         self,
@@ -45,43 +57,54 @@ class PerishableMap[K, V]:
         self._ttl = ttl_seconds
         self._on_evict = on_evict
         self._clock = clock
+        self._lock = threading.RLock()
         self._entries: dict[K, _TimedEntry[V]] = {}
 
     def put(self, key: K, value: V) -> None:
         """Inserts/overwrites, evicting expired (and, for new keys only, over-capacity) first."""
-        self._evict_expired()
-        if key not in self._entries:  # divergence: overwrite at capacity evicts nothing
-            self._evict_over_capacity()
-        self._entries[key] = _TimedEntry(value, self._clock())
+        with self._lock:
+            evicted = self._evict_expired()
+            if key not in self._entries:  # divergence: overwrite at capacity evicts nothing
+                evicted += self._evict_over_capacity()
+            self._entries[key] = _TimedEntry(value, self._clock())
+        for entry in evicted:
+            self._on_evict(entry.value)
 
     def get(self, key: K) -> V | None:
         """Returns the value for ``key`` or ``None``."""
-        entry = self._entries.get(key)
-        return entry.value if entry is not None else None
+        with self._lock:
+            entry = self._entries.get(key)
+            return entry.value if entry is not None else None
 
     def remove(self, key: K) -> V | None:
         """Removes and returns the value for ``key`` or ``None``."""
-        entry = self._entries.pop(key, None)
-        return entry.value if entry is not None else None
+        with self._lock:
+            entry = self._entries.pop(key, None)
+            return entry.value if entry is not None else None
 
     def size(self) -> int:
         """Number of entries currently held."""
-        return len(self._entries)
+        with self._lock:
+            return len(self._entries)
 
-    def _evict_expired(self) -> None:
+    def _evict_expired(self) -> list[_TimedEntry[V]]:
+        """Removes the expired entries; the caller (holding the lock) calls back afterwards."""
         now = self._clock()
-        expired = [k for k, e in self._entries.items() if now - e.created > self._ttl]
-        for key in expired:
-            entry = self._entries.pop(key)
-            self._on_evict(entry.value)
-
-    def _evict_over_capacity(self) -> None:
+        evicted: list[_TimedEntry[V]] = []
+        for key, examined in list(self._entries.items()):
+            if now - examined.created > self._ttl and self._entries.get(key) is examined:
+                del self._entries[key]
+                evicted.append(examined)
+        return evicted
+
+    def _evict_over_capacity(self) -> list[_TimedEntry[V]]:
+        evicted: list[_TimedEntry[V]] = []
         while len(self._entries) >= self._max_capacity:
             oldest = self._find_oldest()
             if oldest is None:
                 break
-            entry = self._entries.pop(oldest)
-            self._on_evict(entry.value)
+            evicted.append(self._entries.pop(oldest))
+        return evicted
 
     def _find_oldest(self) -> K | None:
         oldest_key: K | None = None

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/render/indented.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from narrativetrace import exception_message
 from narrativetrace.escape import control_sanitize
 from narrativetrace.nodes import TraceNode
 from narrativetrace.outcomes import Incomplete, Returned, Threw, TraceOutcome
@@ -211,7 +212,7 @@ class IndentedTextRenderer:
         if isinstance(outcome, Returned):
             parts.append(f" → {_return_text(outcome.rendered_value)}")
         elif isinstance(outcome, Threw):
-            message = control_sanitize(str(outcome.exception))
+            message = exception_message.text(outcome.exception)
             parts.append(f" !! {_exception_type(outcome.exception)}: {message}")
             if sig.error_context is not None:
                 parts.append(f" | {control_sanitize(sig.error_context)}")
@@ -224,7 +225,7 @@ class IndentedTextRenderer:
         if isinstance(outcome, Returned):
             parts.append(f"→ {_return_text(outcome.rendered_value)}")
         elif isinstance(outcome, Threw):
-            message = control_sanitize(str(outcome.exception))
+            message = exception_message.text(outcome.exception)
             parts.append(f"!! {_exception_type(outcome.exception)}: {message}")
             if sig.error_context is not None:
                 parts.append(f" | {control_sanitize(sig.error_context)}")

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/render/markdown.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from narrativetrace import exception_message
 from narrativetrace.escape import markdown_code, markdown_text
 from narrativetrace.nodes import TraceNode
 from narrativetrace.outcomes import Incomplete, Returned, Threw, TraceOutcome
@@ -229,7 +230,7 @@ class MarkdownRenderer:
         elif isinstance(outcome, Threw):
             error_indent = "  " * (depth + 1)
             exc_type = markdown_code(type(outcome.exception).__name__)
-            message = markdown_text(str(outcome.exception))
+            message = markdown_text(exception_message.text(outcome.exception))
             parts.append(f"\n\n{error_indent}> ❌ {exc_type}: {message}")
             if sig.error_context is not None:
                 parts.append(f"\n{error_indent}> {markdown_text(sig.error_context)}")
@@ -249,7 +250,7 @@ class MarkdownRenderer:
         elif isinstance(outcome, Threw):
             error_indent = "  " * (depth + 1)
             exc_type = markdown_code(type(outcome.exception).__name__)
-            message = markdown_text(str(outcome.exception))
+            message = markdown_text(exception_message.text(outcome.exception))
             parts.append(f"❌ {exc_type}: {message}")
             if sig.error_context is not None:
                 parts.append(f"\n{error_indent}> {markdown_text(sig.error_context)}")

{narrativetrace-0.4.2 → narrativetrace-0.5.0}/src/narrativetrace/render/prose.py

@@ -12,6 +12,7 @@ Every span is named by its span id in parentheses (``(#1.3)``,
 
 from __future__ import annotations
 
+from narrativetrace import exception_message
 from narrativetrace.escape import control_sanitize
 from narrativetrace.nodes import TraceNode
 from narrativetrace.outcomes import Incomplete, Returned, Threw, TraceOutcome
@@ -165,7 +166,7 @@ class ProseRenderer:
         if isinstance(outcome, Returned) and outcome.rendered_value is not None:
             parts.append(f"{indent}  Returned {outcome.rendered_value}.\n")
         elif isinstance(outcome, Threw):
-            message = control_sanitize(str(outcome.exception))
+            message = exception_message.text(outcome.exception)
             parts.append(f"{indent}  {_exception_type(outcome.exception)}: {message}.\n")
         elif isinstance(outcome, Incomplete):
             parts.append(f"{indent}  ⏳ in-flight.\n")
@@ -176,7 +177,7 @@ class ProseRenderer:
         if isinstance(outcome, Returned) and outcome.rendered_value is not None:
             parts.append(f", returning {outcome.rendered_value}")
         elif isinstance(outcome, Threw):
-            message = control_sanitize(str(outcome.exception))
+            message = exception_message.text(outcome.exception)
             parts.append(f" — {_exception_type(outcome.exception)}: {message}")
             if sig.error_context is not None:
                 parts.append(f" ({control_sanitize(sig.error_context)})")