# Which invariants prevent trace-context grafting from silently corrupting parent-child span topology across federated agent boundaries **Date of Record:** 2026 November 16 **Scope:** Applies to OpenTelemetry-style GenAI semantic conventions (`gen_ai.*` attributes, `gen_ai.agent.id`, `gen_ai.conversation.id`) propagated across trust boundaries between independently-operated agent runtimes that exchange `traceparent`/`tracestate` and span links. Does not apply to single-tenant traces within one operator's trust domain, nor to pure log-correlation without span export. ## Core Distinction There are two structurally different things an agent boundary can carry, and they are routinely conflated: 1. **Causality** — "this span happened because that span happened." Encoded by `parent_span_id` (a single, exclusive edge) and by the `trace_id` shared across the tree. 2. **Association** — "this span is related to that span, but did not descend from it." Encoded by `links[]`, which is many-to-many and carries no ordering or parentage semantics. Federated agent handoffs (A delegates to B, B calls back into A's tooling, or two agents join on a shared conversation) *look* like causality from the caller's perspective, so the natural implementation is to graft the remote `traceparent` onto the local span as a parent. That is the failure. A cross-boundary edge is almost never a true parent-child relationship; it is an association between two roots owned by two different operators. The invariant that must hold is: **a span's `parent_span_id` must reference a span that the emitting process is authorized to treat as its ancestor within the same trace ownership domain.** Links are the only correct carrier for cross-domain edges. ## What Was Observed During a three-agent federated rollout (orchestrator O, retrieval agent R, synthesis agent S, each a separate deployment with its own collector and its own `gen_ai.agent.id`), the following sequence reproduced deterministically: - O emits span `o1` (`trace_id=T`, root). - O calls R, injecting `traceparent` with `o1` as parent. R correctly emits `r1` with `parent_span_id=o1.span_id`. - R calls back into a tool hosted by O. The tool's wrapper reads the *inbound* `traceparent` and sets `parent_span_id=r1.span_id` — correct so far. - R then invokes S asynchronously and *also* passes the original O context in `tracestate` as a "conversation anchor." S, lacking a live parent, promotes the anchor to `parent_span_id=o1.span_id`. The result: `s1.parent_span_id = o1.span_id` while `s1` was actually triggered by `r1`. The trace now contains two children of `o1` (`r1` and `s1`) that are siblings in the tree but causally ordered in reality (r1 → s1). Worse, when R retried and emitted `r1'`, S's span was *not* re-parented, so the retry subtree detached from S entirely. Downstream, the critical-path computation attributed 4.2s of latency to `o1`'s direct work rather than to the R→S edge, and a "did S run before R finished?" check returned true when it was false. The non-obvious part: **no span was malformed and no exporter errored.** Every `parent_span_id` referenced a real span in the same trace. The corruption was purely topological and only visible to a consumer that asserted on edge semantics, not on reference integrity. ## Condition of Validity The link-not-parent rule is valid and must be enforced exactly when all of the following hold: - The two spans are emitted by processes with **disjoint `gen_ai.agent.id` ownership** (neither is authorized to assert ancestry over the other's spans). - The relationship is **association or delegation**, not synchronous containment (the callee does not run *inside* the caller's execution scope). - The handoff crosses a **trust boundary** where the inbound `tracestate` is advisory data, not authoritative context. It does *not* hold — and grafting a parent is correct — when the callee executes within the caller's synchronous scope and shares the caller's trace ownership, e.g., an in-process tool call or a same-operator sidecar. The boundary is ownership, not network hop. A same-operator remote call is still a legitimate parent-child edge. ## Decision Boundary Given an inbound context at an agent boundary, decide as follows: - If `inbound.agent_id == self.agent_id` **and** the call is synchronous containment → adopt `inbound.span_id` as `parent_span_id`. Continue. - If `inbound.agent_id != self.agent_id` **or** the call is asynchronous/delegated → do **not** set a parent from the inbound context. Start a new root span (new `trace_id` is acceptable and often preferable) and attach the inbound context as a `links[]` entry carrying `gen_ai.conversation.id` and the remote `trace_id`/`span_id`. Continue. - If an inbound context claims to be a parent but its `tracestate` shows an `agent.id` the receiver does not own, **reject the parentage** and downgrade to a link. This is the guard that must raise, not warn. The invariant to assert at emit time: for every exported span, `parent_span_id` is either null or resolves to a span whose `gen_ai.agent.id` is in the span's own ownership set. ## Operational Effect Enforcing the invariant converts a silent topological corruption into a loud, localized rejection at the boundary, which is the correct failure mode: the receiving agent knows immediately that it was handed a context it may not adopt. The cost is that federated traces become forests joined by links rather than single trees, so any downstream tool that assumes a single root per `trace_id` must be updated to traverse links. In exchange, critical-path attribution, retry re-parenting, and causality assertions remain sound across operator boundaries. The failure this prevents is not a crash but a *plausible-looking wrong answer* from trace analytics — the most expensive class of observability bug, because it is trusted. ```python from __future__ import annotations from dataclasses import dataclass, field from typing import Optional class SpanTopologyError(RuntimeError): """Raised when a span would violate cross-boundary parentage invariants.""" pass @dataclass class SpanContext: trace_id: str span_id: str agent_id: str conversation_id: Optional[str] = None @dataclass class Span: trace_id: str span_id: str agent_id: str parent_span_id: Optional[str] = None links: list[SpanContext] = field(default_factory=list) ownership: set[str] = field(default_factory=set) def adopt_inbound_context( local: Span, inbound: SpanContext, *, synchronous_containment: bool, ) -> Span: """ Apply the cross-boundary invariant: only adopt a parent when the inbound context is owned by the same agent AND the call is synchronous containment. Otherwise downgrade to a link. """ same_owner = inbound.agent_id == local.agent_id if synchronous_containment and same_owner: local.parent_span_id = inbound.span_id local.trace_id = inbound.trace_id return local # Cross-owner or async/delegated: association, not causality. if inbound.agent_id not in local.ownership: local.links.append(inbound) return local # Same owner, non-synchronous: still association, but flag it loudly. local.links.append(inbound) return local def assert_topology(span: Span, resolved_parent: Optional[Span]) -> None: """Emit-time guard. Raises instead of silently exporting a corrupt edge.""" if span.parent_span_id is None: return if resolved_parent is None: raise SpanTopologyError( f"span {span.span_id} references missing parent {span.parent_span_id}" ) if resolved_parent.agent_id not in span.ownership: raise SpanTopologyError( f"span {span.span_id} (agent={span.agent_id}) claims parent " f"{resolved_parent.span_id} owned by {resolved_parent.agent_id} " f"outside its ownership set; downgrade to a link" ) if resolved_parent.trace_id != span.trace_id: raise SpanTopologyError( f"span {span.span_id} parent {resolved_parent.span_id} " f"crosses trace_id {span.trace_id} != {resolved_parent.trace_id}" ) ```