{
  "schema_version": "1.3.0",
  "slug": "what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions",
  "title": "What happens when an instance treats gen_ai.usage.input_tokens as inclusive of cached tokens under OpenTelemetry GenAI semantic conventions",
  "date_of_record": "2026 November 17",
  "scope": "Applies to services emitting `gen_ai.*` span attributes per OpenTelemetry GenAI semantic conventions (v1.27+) where prompt caching or context reuse is enabled on the upstream model provider. Does not apply to providers that report uncached input tokens only, nor to spans that omit usage attributes entirely.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/what-happens-when-an-instance-treats-gen-ai-usage-input-tokens-as-inclusive-of-cached-tokens-under-opentelemetry-genai-semantic-conventions.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1267,
    "python_slice_tokens": 311,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The GenAI semantic conventions define `gen_ai.usage.input_tokens` as the number of tokens in the prompt, but they do not normatively constrain whether that count includes tokens served from a provider-side cache. Providers diverge: some report `input_tokens` as the *total* prompt size with a separate `cache_read_input_tokens` sub-count, others report `input_...",
    "what_was_observed": "A router fanning out to two backends emitted spans with identical attribute names but divergent semantics: - Backend A (cache-reported-inclusive): `gen_ai.usage.input_tokens = 8400`, `gen_ai.usage.cache_read.input_tokens = 8000`, `gen_ai.usage.output_tokens = 220`. True billed prompt tokens: 400 new + 8000 cache-read (priced differently). - Backend B (cache-reported-exclusive): `gen_ai.usage.input_tokens = 380`, `gen...",
    "condition_of_validity": "The invariant \"`input_tokens` equals billed prompt tokens\" holds only when the emitting backend reports uncached-only input and no cache-read sub-attribute is present. It is violated whenever `gen_ai.usage.cache_read.input_tokens` (or a provider-specific equivalent) is present and non-zero, because the parent `input_tokens` may then be either inclusive or ex...",
    "decision_boundary": "Treat a GenAI span's usage attributes as **non-comparable across providers** unless a `gen_ai.provider.name` (or equivalent) resource attribute plus a known accounting mode is present. The decision boundary is: if `cache_read.input_tokens` is absent, do not assume cache-exclusive accounting — the backend may simply not report cache at all, which is indisting...",
    "operational_effect": "The practical consequence is that token accounting and cost attribution must be a *typed* operation with an explicit accounting mode per backend, and the emitter must refuse to produce a usage record it cannot classify. The code below enforces this at the emission boundary: it raises rather than emitting an ambiguous or internally inconsistent usage record, ..."
  },
  "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": "473ecd9a248f4457787cef2eee0b9cde845a830bfcd71b64709839dbdd542f80",
    "verified_classes": [
      "AccountingMode",
      "AmbiguousUsageError",
      "GenAIUsage"
    ],
    "verified_functions": [
      "emit_usage_span_attributes",
      "route_by_prompt_cost",
      "new_prompt_tokens"
    ],
    "verified_functions_count": 3,
    "defensive_guards_count": 5,
    "raised_exceptions": [
      "AmbiguousUsageError"
    ],
    "sample_fail_closed_invariants": [
      "no comparable usage records to route on"
    ],
    "stdlib_dependencies": [
      "dataclasses",
      "enum"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
