{
  "schema_version": "1.3.0",
  "slug": "what-structural-signals-indicate-opentelemetry-genai-span-attribute-invariants-break-at-the-tool-call-boundary-when-token-accounting-and-agent-invocat",
  "title": "What structural signals indicate: OpenTelemetry GenAI span attribute invariants break at the tool-call boundary when token accounting and agent-invocation nesting are conflated",
  "date_of_record": "2026 November 17",
  "scope": "Applies to OpenTelemetry GenAI semantic conventions (gen_ai.*) as emitted by LLM SDK instrumentation for chat completions, tool/function calls, and agent invocations. Does not apply to non-GenAI spans, nor to custom attributes outside the gen_ai namespace; nor does it prescribe behavior for streaming responses where intermediate chunks are not promoted to span events.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/what-structural-signals-indicate-opentelemetry-genai-span-attribute-invariants-break-at-the-tool-call-boundary-when-token-accounting-and-agent-invocat.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/what-structural-signals-indicate-opentelemetry-genai-span-attribute-invariants-break-at-the-tool-call-boundary-when-token-accounting-and-agent-invocat.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/what-structural-signals-indicate-opentelemetry-genai-span-attribute-invariants-break-at-the-tool-call-boundary-when-token-accounting-and-agent-invocat.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1723,
    "python_slice_tokens": 392,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The GenAI semantic conventions define three attribute families that are structurally independent but frequently emitted by a single instrumentation layer as if they shared a lifecycle: **token usage** (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`), **tool-call identity** (`gen_ai.tool.name`, `gen_ai.tool.call.id`), and **agent invocation** (`gen...",
    "what_was_observed": "In a multi-agent deployment (planner → tool executor → synthesizer) instrumented with the standard GenAI semconv, we observed the following structural signals: 1. **Orphaned tool spans.** Spans with `gen_ai.operation.name=execute_tool` and a valid `gen_ai.tool.call.id` were emitted as children of the *agent* span rather than the *chat* span that produced the tool call. The `gen_ai.tool.call.id` on the tool span did n...",
    "condition_of_validity": "The invariant \"token attributes belong only to `chat` spans\" holds **only when** the instrumentation emits one `chat` span per model API call and does not split a single model call across multiple spans (e.g., request/response spans). If instrumentation uses a request span + response span pattern, token attributes legitimately appear on the response span, an...",
    "decision_boundary": "The boundary at which instrumentation and consumers must diverge: - **If** `gen_ai.operation.name == \"chat\"` **then** token attributes are expected and tool-call attributes are optional (present when the response contains tool calls). - **If** `gen_ai.operation.name == \"execute_tool\"` **then** `gen_ai.tool.name` and `gen_ai.tool.call.id` are expected; token ...",
    "operational_effect": "The practical consequence is that GenAI trace validation must be **operation-scoped**, not span-scoped. A validator that checks \"every gen_ai span has tokens\" produces false positives on every tool span and every agent wrapper, and false negatives on chat spans that legitimately report zero tokens (cached responses, empty completions). Cost pipelines that ag..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "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": "804458177776880c2f259101af5ddc107565ee1fe3bd361445f0143b36704def",
    "verified_classes": [
      "GenAISpanInvariantError",
      "GenAISpan"
    ],
    "verified_functions": [
      "validate_genai_span",
      "validate_trace"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 8,
    "raised_exceptions": [
      "GenAISpanInvariantError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
