feat: SDK-06 W3C traceparent propagation; closes #1

Add _traceparent() to _http.py — generates 00-<32hex>-<16hex>-01 per
W3C Trace Context spec. Inject into every get_json() and post_json() call.
In submit_async(), generate one traceparent shared across the discover
GET and node POST so both spans share the same trace-id.

Two new tests: header format validation + shared trace-id within submit().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: RobLe3

src/iicp_client/_http.py

@@ -1,6 +1,7 @@
 """Internal HTTP helpers — TLS context, timeout normalization."""
 from __future__ import annotations
 
+import secrets
 import ssl
 import time
 from typing import Any
@@ -10,6 +11,17 @@
 from iicp_client.errors import IicpError, from_http
 
 
+def _traceparent() -> str:
+    """Generate a W3C traceparent header value (SDK-06).
+
+    Format: 00-<trace-id>-<parent-id>-01
+    trace-id  = 16 random bytes as 32 hex chars
+    parent-id =  8 random bytes as 16 hex chars
+    flags     = 01 (sampled)
+    """
+    return f"00-{secrets.token_hex(16)}-{secrets.token_hex(8)}-01"
+
+
 def _tls_context(verify: bool) -> ssl.SSLContext | bool:
     if not verify:
         # SDK-05: tls_verify=False only permitted in debug; prod builds must verify
@@ -27,13 +39,15 @@ async def get_json(
     timeout_ms: int = 5_000,
     component: str = "directory",
     tls_verify: bool = True,
+    traceparent: str | None = None,
 ) -> dict[str, Any]:
     timeout = timeout_ms / 1000.0
+    headers = {"traceparent": traceparent or _traceparent()}
     try:
         async with httpx.AsyncClient(
             timeout=timeout, verify=_tls_context(tls_verify)
         ) as client:
-            resp = await client.get(url, params=params)
+            resp = await client.get(url, params=params, headers=headers)
     except httpx.TimeoutException:
         raise IicpError(
             code="IICP-E003",
@@ -60,15 +74,17 @@ async def post_json(
     timeout_ms: int = 30_000,
     component: str = "adapter",
     tls_verify: bool = True,
+    traceparent: str | None = None,
 ) -> tuple[dict[str, Any], int]:
     """Returns (response_body, elapsed_ms)."""
     timeout = (timeout_ms / 1000.0) + 2.0
+    headers = {"traceparent": traceparent or _traceparent()}
     t0 = time.monotonic()
     try:
         async with httpx.AsyncClient(
             timeout=timeout, verify=_tls_context(tls_verify)
         ) as client:
-            resp = await client.post(url, json=body)
+            resp = await client.post(url, json=body, headers=headers)
     except httpx.TimeoutException:
         raise IicpError(
             code="IICP-E003",

src/iicp_client/client.py

@@ -6,7 +6,7 @@
 import uuid
 from typing import Any
 
-from iicp_client._http import get_json, post_json
+from iicp_client._http import _traceparent, get_json, post_json
 from iicp_client.errors import IicpError
 from iicp_client.types import (
     ChatChoice,
@@ -51,6 +51,8 @@ async def discover_async(
         self,
         intent: str,
         options: DiscoverOptions | None = None,
+        *,
+        traceparent: str | None = None,
     ) -> NodeList:
         """Discover nodes capable of handling *intent*."""
         opts = options or DiscoverOptions()
@@ -73,6 +75,7 @@ async def discover_async(
             timeout_ms=5_000,
             component="directory",
             tls_verify=self._cfg.tls_verify,
+            traceparent=traceparent,
         )
         elapsed = int((time.monotonic() - t0) * 1000)
 
@@ -95,14 +98,18 @@ async def submit_async(self, request: TaskRequest) -> TaskResponse:
         """Discover → select best node → submit task.
 
         Retries up to max_retries on transient errors (SDK-01).
+        A single W3C traceparent is generated per submit call and propagated
+        to both the discover request and the node POST (SDK-06).
         """
         self._validate_intent(request.intent)
+        tp = _traceparent()  # SDK-06: one trace per operation, shared across calls
         node_list = await self.discover_async(
             request.intent,
             DiscoverOptions(
                 region=request.constraints.region or self._cfg.region,
                 qos=request.constraints.qos,
             ),
+            traceparent=tp,
         )
         if not node_list.nodes:
             raise IicpError(
@@ -135,6 +142,7 @@ async def submit_async(self, request: TaskRequest) -> TaskResponse:
                     timeout_ms=request.constraints.timeout_ms,
                     component="adapter",
                     tls_verify=self._cfg.tls_verify,
+                    traceparent=tp,
                 )
                 return TaskResponse(
                     task_id=raw.get("task_id", task_id),

tests/test_client.py

@@ -234,3 +234,41 @@ def test_discover_passes_min_reputation_and_model():
     url = str(route.calls[0].request.url)
     assert "min_reputation=0.7" in url
     assert "model=phi3%3Amini" in url or "model=phi3:mini" in url
+
+
+# ---------------------------------------------------------------------------
+# SDK-06: W3C traceparent propagation
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+def test_sdk06_traceparent_sent_on_discover():
+    """SDK-06: every outbound request carries a W3C traceparent header."""
+    route = respx.get(DISCOVER_URL).mock(return_value=httpx.Response(200, json=GOOD_NODES))
+    client = IicpClient(ClientConfig(directory_url=DIRECTORY))
+    client.discover("urn:iicp:intent:llm:chat:v1")
+    header = route.calls[0].request.headers.get("traceparent", "")
+    # format: 00-<32hex>-<16hex>-01
+    parts = header.split("-")
+    assert len(parts) == 4, f"bad traceparent: {header!r}"
+    assert parts[0] == "00"
+    assert len(parts[1]) == 32
+    assert len(parts[2]) == 16
+    assert parts[3] == "01"
+
+
+@respx.mock
+def test_sdk06_traceparent_shared_across_submit():
+    """SDK-06: discover + node POST share the same trace-id within one submit()."""
+    disc_route = respx.get(DISCOVER_URL).mock(return_value=httpx.Response(200, json=GOOD_NODES))
+    task_route = respx.post(TASK_URL).mock(
+        return_value=httpx.Response(200, json={"task_id": "t1", "status": "success", "result": {}})
+    )
+    client = IicpClient(ClientConfig(directory_url=DIRECTORY))
+    client.submit(TaskRequest(intent="urn:iicp:intent:llm:chat:v1", payload={}))
+    disc_tp = disc_route.calls[0].request.headers.get("traceparent", "")
+    task_tp = task_route.calls[0].request.headers.get("traceparent", "")
+    # both must have the same trace-id (index 1)
+    assert disc_tp.split("-")[1] == task_tp.split("-")[1], (
+        f"trace-id mismatch: discover={disc_tp!r} task={task_tp!r}"
+    )