docs: changelog and docstrings for tracing split and transport fixes

- Add CHANGELOG entries for OperationTracingPolicy and the new outermost
  Stage.OPERATION, the TracingPolicy lifecycle split (with a migration note
  for pipelines assembled by hand), and the urllib/asyncio transport
  corrections (Content-Length under Content-Encoding, chunked-framing
  detection, and out-of-range status wording).
- Document that the tracing and logging policies are sync-only and the async
  pipeline carries no tracing, in both the tracing module docstring and the
  changelog's scope boundaries.
- List Stage.OPERATION among the pillar stages in the staged-builder docstring.
- Remove leftover shorthand prefixes from a few test comments, keeping the
  explanatory text.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: OmarAlJarrah

CHANGELOG.md

@@ -8,13 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 A round of platform improvements to `dexpace-sdk-core`: new optional building
-blocks (typed serialization, webhook verification, pagination, two pipeline
-policies), tightened retry and tracing behaviour, and a batch of correctness
-fixes across bodies, SSE parsing, Digest auth, and error reporting. Most of this
-lands in `core`; the transport adapters additionally get consistent connect- vs
-read-phase timeout classification and tighter resource release. The only removed
-public symbol is the unused `RetryConfig` (see Removed); existing code otherwise
-continues to work without modification.
+blocks (typed serialization, webhook verification, pagination, three pipeline
+policies), tightened retry behaviour, a corrected per-operation tracing
+lifecycle, and a batch of correctness fixes across bodies, SSE parsing, Digest
+auth, and error reporting. Most of this lands in `core`; the transport adapters
+additionally get consistent connect- vs read-phase timeout classification,
+tighter resource release, and a set of edge-case corrections (status-code
+reporting, chunked-framing detection, and content-length under content-encoding).
+The only removed public symbol is the unused `RetryConfig` (see Removed);
+existing code otherwise continues to work without modification — with one
+behavioural note for hand-assembled pipelines (see *Tracing lifecycle* under
+Changed).
 
 ### Added
 
@@ -37,6 +41,13 @@ continues to work without modification.
 - **Client-identity policy** (`pipeline.policies.client_identity`, plus its
   async twin). Sets a consistent `User-Agent` / client-identity header derived
   from the configured application id and SDK version.
+- **Per-operation tracing policy** (`OperationTracingPolicy` in
+  `pipeline.policies.tracing_policy`, with a new outermost `Stage.OPERATION`).
+  Emits the per-operation `HttpTracer` lifecycle (`operation_started`, then
+  exactly one `operation_succeeded` / `operation_failed`) from outside the retry
+  and redirect wrappers, so the reported outcome reflects the final result of
+  the whole call rather than a single attempt or hop. Sync-only, in line with
+  the rest of the tracing stack; the async pipeline carries no tracing.
 - **HTTP tracer** (`instrumentation.http_tracer`). An adapter-style tracer base
   whose per-event methods default to no-ops, so a subclass overrides only the
   events it cares about. Wired through the tracing policy for span emission.
@@ -58,6 +69,15 @@ continues to work without modification.
   cancellation cleanly between attempts.
 - **Tracing and redirect policies** now emit tracer events and carry correlation
   through redirects, with credentials stripped on cross-origin redirects.
+- **Tracing lifecycle** (`pipeline.policies.tracing_policy`). The per-operation
+  `HttpTracer` lifecycle moved out of `TracingPolicy` into the new
+  `OperationTracingPolicy`; `TracingPolicy` now emits only its per-attempt span
+  and the per-request events (`request_sent`, `response_headers_received`,
+  `response_received`). `default_pipeline` wires both, so callers who use it are
+  unaffected. A pipeline assembled by hand that wants the operation lifecycle
+  must now add `OperationTracingPolicy` alongside `TracingPolicy` — a bare
+  `TracingPolicy` no longer emits `operation_started` / `operation_succeeded` /
+  `operation_failed`.
 - **Default pipelines** (`pipeline.defaults`). The standard sync/async stacks now
   assemble the new idempotency and client-identity policies alongside the
   existing retry, redirect, logging, and tracing policies.
@@ -96,6 +116,26 @@ continues to work without modification.
   `async_response_body`). Cancelling an in-flight read now releases the
   underlying resources instead of leaking them, and re-raises `CancelledError`
   after cleanup.
+- **Per-operation tracing outcome** (`pipeline.policies.tracing_policy`). A call
+  retried after a failed first attempt no longer reports `operation_failed` for
+  the discarded attempt (it reports the single `operation_succeeded` it ends on),
+  and a redirect whose later hop fails no longer reports `operation_succeeded`
+  for the earlier 3xx hop. The lifecycle now fires exactly once and reflects the
+  final outcome. See *Tracing lifecycle* under Changed for the API shape.
+- **`Content-Length` under `Content-Encoding`** (`http.stdlib.urllib_http_client`).
+  `UrllibHttpClient` no longer drops a valid `Content-Length` when
+  `Content-Encoding` is present: `http.client` does not decode content codings,
+  so the body it serves is the wire payload whose length the header describes,
+  and the length is now surfaced as-is. (The decompressing requests/httpx/aiohttp
+  adapters still drop it, since they hand back a decoded stream.)
+- **Chunked-framing detection** (`http.stdlib.asyncio_http_client`). The
+  `Transfer-Encoding` check matches the `chunked` coding by token rather than
+  substring, so a coding whose name merely contains `chunked` (e.g. `x-chunked`)
+  is no longer mistaken for chunked framing.
+- **Out-of-range status reporting** (`http.stdlib.urllib_http_client`,
+  `asyncio_http_client`). Both now raise a `ServiceResponseError` worded
+  `Invalid status code: …` for a status outside 100–599, matching the other
+  adapters.
 
 ### Verified
 
@@ -113,6 +153,9 @@ The following were intentionally left out of this round and are **not** included
   errors themselves.
 - **`sendfile` fast-path** — file bodies are streamed via the existing
   `iter_bytes` path; no zero-copy `sendfile` transport optimisation was added.
+- **Async tracing / logging** — the tracing and logging policies (including the
+  new `OperationTracingPolicy`) ship sync-only; `default_async_pipeline` carries
+  no tracing, and async callers handle per-operation observability themselves.
 - **MCP support** — no Model Context Protocol integration is included.
 - **Java SDK items** — the Java counterpart lives in a separate repository and
   was out of scope here.

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/policies/tracing_policy.py

@@ -29,6 +29,10 @@
 default tracer factory returns ``NOOP_HTTP_TRACER`` and the no-op span carries
 the sentinel trace ids. Disable either per-call by setting
 ``ctx.options["tracing_enabled"] = False``.
+
+Both policies are sync-only, in line with the rest of the tracing and logging
+stack; ``default_async_pipeline`` carries no tracing, so async callers own
+per-operation observability on their side.
 """
 
 from __future__ import annotations

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/staged_builder.py

@@ -7,8 +7,8 @@
 constructor. Policies declare their ``STAGE``; the builder slots them into
 stage buckets and at ``build()`` time flattens to a list in stage order.
 
-Pillar stages (`REDIRECT`, `RETRY`, `AUTH`, `LOGGING`, `SERDE`) admit at
-most one policy. A second `append` of a pillar raises by default — use
+Pillar stages (`OPERATION`, `REDIRECT`, `RETRY`, `AUTH`, `LOGGING`, `SERDE`)
+admit at most one policy. A second `append` of a pillar raises by default — use
 ``replace(target, new)`` for explicit swaps or ``append(p, force=True)``
 for the rare legitimate use case (test fixtures, runtime composition).
 """

packages/dexpace-sdk-core/tests/pipeline/test_tracer_emission.py

@@ -517,7 +517,7 @@ def test_redirect_then_failure_reports_operation_failed(self) -> None:
         assert failed == [boom]
 
 
-# ----- request_sent fires for unknown-length bodies (L19) -----------------
+# ----- request_sent fires for unknown-length bodies -----------------
 
 
 class TestRequestSentUnknownLength:

packages/dexpace-sdk-http-stdlib/tests/test_asyncio_http_client.py

@@ -226,7 +226,7 @@ def _header_value(head: list[str], name: str) -> str | None:
 
 
 async def test_host_header_includes_non_default_port() -> None:
-    # M1: a non-default port must appear in the Host header (RFC 9112 §3.2).
+    # A non-default port must appear in the Host header (RFC 9112 §3.2).
     sink: dict[str, list[str]] = {}
     gen = _serve(await _collect_head(sink))
     base = await anext(gen)
@@ -241,7 +241,7 @@ async def test_host_header_includes_non_default_port() -> None:
 
 
 async def test_empty_post_body_sends_content_length_zero() -> None:
-    # L17: a body-bearing method with no payload must advertise
+    # A body-bearing method with no payload must advertise
     # Content-Length: 0 (RFC 9110 §8.6).
     sink: dict[str, list[str]] = {}
     gen = _serve(await _collect_head(sink))
@@ -289,7 +289,7 @@ async def test_post_with_body_sets_content_length() -> None:
 
 
 async def test_plain_http_ignores_supplied_ssl_context() -> None:
-    # M2: a caller-supplied ssl_context must not trigger a TLS handshake on
+    # A caller-supplied ssl_context must not trigger a TLS handshake on
     # a plain http:// URL — the request must still succeed over plaintext.
     async def ok(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
         await _read_request_head(reader)
@@ -310,7 +310,7 @@ async def ok(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None
 
 
 async def test_chunked_response_raises_service_response_error() -> None:
-    # M3: a chunked response cannot be dechunked by this reference client, so
+    # A chunked response cannot be dechunked by this reference client, so
     # it must fail loudly rather than silently return an empty body.
     async def chunked(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
         await _read_request_head(reader)
@@ -333,7 +333,7 @@ async def chunked(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) ->
 
 
 async def test_multiline_transfer_encoding_with_chunked_not_first_raises() -> None:
-    # M3: Transfer-Encoding may be split across lines with ``chunked`` NOT
+    # Transfer-Encoding may be split across lines with ``chunked`` NOT
     # first (alongside a misleading Content-Length). The client must still
     # detect chunked framing and refuse to read the bytes as a fixed-length
     # body, rather than parsing chunk framing as the payload — the exact
@@ -377,7 +377,7 @@ def test_is_chunked_matches_coding_token_not_substring() -> None:
 
 
 async def test_connection_close_framed_body_read_to_eof() -> None:
-    # M3: a response without Content-Length is connection-close framed; the
+    # A response without Content-Length is connection-close framed; the
     # body must be read to EOF, not fabricated as empty.
     async def close_framed(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
         await _read_request_head(reader)

packages/dexpace-sdk-http-stdlib/tests/test_urllib_http_client.py

@@ -120,7 +120,7 @@ def test_post_with_body(echo_server: str) -> None:
 class _RedirectHandler(socketserver.StreamRequestHandler):
     """Replies with a 302 pointing at another origin and a small body.
 
-    Pins H1: the transport must NOT follow the redirect itself. If it did,
+    Pins that the transport must NOT follow the redirect itself. If it did,
     the second hop would fail (the target host is unroutable) or the response
     would carry the followed target's status — either way not a 302.
     """
@@ -158,7 +158,7 @@ def redirect_server() -> Iterator[str]:
 
 
 def test_redirect_is_not_followed(redirect_server: str) -> None:
-    # H1: a 302 must surface to the pipeline as a 302 Response, not be
+    # A 302 must surface to the pipeline as a 302 Response, not be
     # transparently followed by the transport (which would also leak the
     # Authorization header cross-origin).
     client = UrllibHttpClient(timeout=2.0)
@@ -340,7 +340,7 @@ def test_content_length_surfaced_under_content_encoding() -> None:
 
 
 def test_read_failure_maps_to_service_response_error() -> None:
-    # M5: a read-phase failure on the raw HTTPResponse must surface as an
+    # A read-phase failure on the raw HTTPResponse must surface as an
     # SdkError, not a bare OSError / IncompleteRead.
     class _BoomResponse(_TrackingResponse):
         def read(self, size: int = -1) -> bytes: