Clarify terminal-attempt scope, rename reader

Rename current_terminal_attempt_index to the underscore-prefixed
_current_terminal_attempt_index (it is internal; only
FailureIsolationMiddleware reads it) and move it to the internal __all__
section. Reword the ContextVar + scope comments: a retry recording
without an enclosing isolation scope does leave a non-None ambient value,
but it is never observed because the sole reader shadows it with None on
entry.

Author: chris-colinsky

src/openarmature/graph/middleware/failure_isolation.py

@@ -40,14 +40,14 @@
 from typing import Any
 
 from openarmature.observability.correlation import (
+    _current_terminal_attempt_index,
     _reset_terminal_attempt_index,
     _set_terminal_attempt_index,
     current_attempt_index,
     current_branch_name,
     current_dispatch,
     current_fan_out_index,
     current_namespace_prefix,
-    current_terminal_attempt_index,
 )
 
 from ._core import NextCall
@@ -137,8 +137,9 @@ async def __call__(self, state: Any, next_: NextCall) -> Mapping[str, Any]:
         # Establish a clean terminal-attempt scope: an inner
         # RetryMiddleware records its final / exhausting attempt here on
         # give-up, and _emit_event reports it (proposal 0050 §6.3). The
-        # ``None`` on entry shadows any stale value from a prior node; the
-        # finally cleans up so it never leaks to a sibling / next node.
+        # ``None`` on entry shadows any stale ambient value so this call
+        # reads correctly; the finally restores the prior value (token
+        # semantics), and the next isolation call shadows again on entry.
         terminal_token = _set_terminal_attempt_index(None)
         try:
             try:
@@ -218,7 +219,7 @@ def _emit_event(self, state: Any, exc: Exception, degraded: Mapping[str, Any]) -
         # already closed by delivery time (their completed event precedes
         # this one on the serial queue), so observers parent the marker
         # under the invocation span and correlate by ``namespace`` + name.
-        terminal_attempt = current_terminal_attempt_index()
+        terminal_attempt = _current_terminal_attempt_index()
         attempt_index = terminal_attempt if terminal_attempt is not None else current_attempt_index()
         dispatch(
             FailureIsolatedEvent(

src/openarmature/observability/correlation.py

@@ -492,9 +492,10 @@ def _reset_attempt_index(token: Token[int]) -> None:
 # rule mandates. On give-up, retry records the final attempt here; the
 # enclosing FailureIsolationMiddleware establishes the scope (None on
 # entry, reset on exit) and reads it, falling back to ``attempt_index``
-# when no retry exhausted. Scoped by the isolation middleware so it never
-# leaks across nodes; the sole reader is FailureIsolationMiddleware, which
-# always shadows any stale value with its own ``None`` on entry.
+# when no retry exhausted. A retry that records without an enclosing
+# isolation scope leaves a non-None value in the ambient context, but it
+# is never OBSERVED: the sole reader (FailureIsolationMiddleware) shadows
+# any such stale value with its own ``None`` on entry before reading.
 #
 # Two setters by design: ``_set`` / ``_reset`` bracket the isolation SCOPE
 # (token-based, mirroring ``_attempt_index``); ``_record`` is retry's
@@ -513,7 +514,7 @@ def _reset_attempt_index(token: Token[int]) -> None:
 )
 
 
-def current_terminal_attempt_index() -> int | None:
+def _current_terminal_attempt_index() -> int | None:
     """Return the final / exhausting attempt index recorded by a retry
     that gave up within the current FailureIsolationMiddleware scope, or
     ``None`` when no retry exhausted. Internal."""
@@ -616,12 +617,12 @@ def _reset_active_observer_span(token: Token[object | None]) -> None:
     "current_fan_out_index_chain",
     "current_invocation_id",
     "current_namespace_prefix",
-    "current_terminal_attempt_index",
     "validate_invocation_id",
     # Engine-internal lifecycle helpers — exported so the engine in
     # ``openarmature.graph.compiled`` can drive set/reset without
     # pyright's strict ``reportUnusedFunction`` flagging them as
     # dead. Underscore-prefixed; not part of the user-facing API.
+    "_current_terminal_attempt_index",
     "_record_terminal_attempt_index",
     "_reset_active_dispatch",
     "_reset_active_observer_span",