{
  "schema_version": "1.3.0",
  "slug": "why-does-an-instance-lose-parent-child-span-correlation-across-llm-calls-retrievals-and-agent-handoffs",
  "title": "Why does an instance lose parent-child span correlation across LLM calls, retrievals, and agent handoffs",
  "date_of_record": "2026 November 15",
  "scope": "Applies to distributed tracing of GenAI workloads where a single logical operation (a user request, an agent turn) is composed of heterogeneous span-emitting components — LLM inference clients, vector retrievers, tool executors, and sub-agent handoffs — each potentially running in a different process, container, or trust domain. Does not apply to single-process, single-threaded tracing where the span context is passed by direct object reference and never crosses a serialization boundary.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/why-does-an-instance-lose-parent-child-span-correlation-across-llm-calls-retrievals-and-agent-handoffs.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-lose-parent-child-span-correlation-across-llm-calls-retrievals-and-agent-handoffs.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-lose-parent-child-span-correlation-across-llm-calls-retrievals-and-agent-handoffs.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1710,
    "python_slice_tokens": 355,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The failure is not \"missing traces\" and it is not \"broken spans.\" It is **context propagation loss at a heterogeneous boundary**: the trace exists, every span exists, every span has a valid `trace_id` — but the `parent_span_id` on one or more spans points to a span that the collector never received, or points to `null` where a parent should exist. The result...",
    "what_was_observed": "In a three-tier agent pipeline (orchestrator → retrieval sub-agent → LLM synthesis), traces arrived with the orchestrator root and the final LLM span both present and correctly linked by `trace_id`, but with the retrieval spans forming an isolated subtree whose root had `parent_span_id = null`. The collector's trace assembly reported the trace as complete (all spans present) yet the tree view showed two roots. Instru...",
    "condition_of_validity": "The parent-child invariant holds **only when the span context is carried across every boundary by an explicit, serialized carrier** — the W3C `traceparent`/`tracestate` headers for HTTP, a message attribute for the queue, an explicit field in the task payload for in-process handoffs. It is **not** valid to rely on: - ambient `contextvars` crossing a process ...",
    "decision_boundary": "When a trace renders as a forest, the decision is: **do not attempt to repair parentage post-hoc by heuristic stitching** (matching on timestamps or `trace_id` proximity). Heuristic stitching produces plausible but false trees and destroys the auditability that motivated tracing. Instead: 1. Treat a forest as a **propagation defect**, not a display defect. L...",
    "operational_effect": "Downstream consumers of these traces — cost attribution, latency decomposition, agent-decision audits — silently degrade. Cost attribution that sums child-span token counts under a parent undercounts by exactly the fraction of spans that became roots. Latency decomposition that computes `parent.duration - sum(child.duration)` attributes the entire retrieval ..."
  },
  "matched_failure_symptoms": [
    "SUBPROCESS_PIPE_HANG_OR_FD_LEAK"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "80e47c2477fd5cb333a5faaf18d51edd6577e19660d971b1b46165ed0a991bf8",
    "verified_classes": [
      "SpanCorrelationError",
      "Span",
      "Trace"
    ],
    "verified_functions": [
      "validate_trace_invariant",
      "assemble_and_quarantine"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 5,
    "raised_exceptions": [
      "SpanCorrelationError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
