Governance and Trace Headers
============================

Use :func:`taimoe.platform.proxy.build_taimoe_headers` when an application
makes an outbound call that should carry Agent identity and trace context.

.. code-block:: python

   from taimoe.platform.proxy import build_taimoe_headers

   headers = build_taimoe_headers(
       runtime_id="support-prod",
       agent_id="support",
       parent_agent_id="router",
       session_id="session-123",
       user_id="privacy-filtered-user-id",
       step="model_call",
   )

The result contains Taimoe-native ``X-Taimoe-*`` headers plus W3C
``traceparent`` and ``tracestate`` values. Trace IDs use 32 lowercase hex
characters and span IDs use 16; malformed or all-zero IDs are rejected.

==============================  =============================================
Header                          Purpose
==============================  =============================================
``X-Taimoe-Runtime-Id``         Calling Runtime identity.
``X-Taimoe-Agent-Id``           Calling Agent identity.
``X-Taimoe-Parent-Agent-Id``    Optional parent Agent.
``X-Taimoe-Trace-Id``           End-to-end trace correlation.
``X-Taimoe-Span-Id``            Current operation correlation.
``X-Taimoe-Parent-Span-Id``     Optional parent operation.
``X-Taimoe-Session-Id``         Conversation/session correlation.
``X-Taimoe-User-Id``            Privacy-filtered end-user identity.
``X-Taimoe-Step``               Lifecycle step label.
``traceparent``                 W3C Trace Context propagation.
``tracestate``                  Taimoe vendor state.
==============================  =============================================

Header values reject empty strings, CR/LF characters, and oversized identity
fields to prevent malformed requests and header injection. Pass
``include_traceparent=False`` when another tracing library owns W3C headers.

The matching parser accepts case-insensitive HTTP mappings and can recover
trace context from ``traceparent`` when Taimoe-native IDs are absent.