Define and adopt a canonical span contract (docs/SPAN_CONTRACT.md)

[fran3cc]

Summary

Define a single canonical span attribute contract that every Respan instrumentation (Python or JS, first-party or OI-delegated) emits. The Respan ingest API at /v2/traces already accepts standard OTLP/HTTP and reads gen_ai.*, llm.*, OpenLLMetry / OpenInference / Traceloop semconv fields directly. The SDK side conforms to that documented API; the backend is not modified.

Today, Python and JS translators have accumulated a parallel set of off-contract respan.* aliases and bare top-level fields (tools, tool_calls, model, prompt_tokens, span_tools, has_tool_calls, etc.) that:

• aren't in the documented public ingest API,
• drift in shape between Python (JSON string for some) and JS (raw array for the same fields after Fix: other problems of vercel instrumentations #195),
• duplicate canonical fields (respan.span.tools ↔ llm.request.functions; tool_calls ↔ gen_ai.completion.0.tool_calls; model ↔ gen_ai.request.model; prompt_tokens ↔ gen_ai.usage.prompt_tokens).

This issue tracks: (a) landing the contract spec, and (b) migrating each translator off the aliases.

What landed in this issue

• Spec doc: docs/SPAN_CONTRACT.md — added in companion PR.

Per-translator cleanup (one PR each)

Migrate each translator to emit canonical-only and add a contract test that asserts no aliases are present.

Python

• python-sdks/instrumentations/respan-instrumentation-openinference — drop respan.span.tools, respan.span.tool_calls, tools, tool_calls, model, prompt_tokens, completion_tokens, total_request_tokens from translator output.
• python-sdks/instrumentations/respan-instrumentation-anthropic-agents — audit and remove any aliases.
• python-sdks/instrumentations/respan-instrumentation-openai-agents — audit and remove any aliases.
• python-sdks/instrumentations/respan-instrumentation-openai — audit (thin wrapper, may already be clean).

JavaScript

• javascript-sdks/instrumentations/respan-instrumentation-vercel — drop raw-array respan.span.tools / respan.span.tool_calls, drop top-level tools / tool_calls / span_tools / has_tool_calls / parallel_tool_calls; tool execution spans must not carry tool_calls.
• javascript-sdks/instrumentations/respan-instrumentation-openinference — audit translator output.
• javascript-sdks/instrumentations/respan-instrumentation-anthropic — audit.
• javascript-sdks/instrumentations/respan-instrumentation-claude-agent-sdk — audit.
• javascript-sdks/instrumentations/respan-instrumentation-openai-agents — audit.
• javascript-sdks/instrumentations/respan-instrumentation-n8n — audit.

respan-sdk constants cleanup

• Python respan_sdk/constants/span_attributes.py — deprecate RESPAN_SPAN_TOOLS, RESPAN_SPAN_TOOL_CALLS, RESPAN_SPAN_HANDOFFS once no translator emits them.
• JS javascript-sdks/respan-sdk/src/types/spanTypes.ts — same deprecation.

Definition of done

• All translators emit canonical fields per docs/SPAN_CONTRACT.md.
• Contract test in each translator package asserts: (a) canonical fields populated correctly per log_type, (b) no off-contract aliases present.
• Public ingest API at /v2/traces is unchanged. Backend is unchanged.

Reference

• Spec: docs/SPAN_CONTRACT.md
• Public ingest contract: https://www.respan.ai/docs/apis/traces/create-trace
• Memory rule: SDK conforms to existing API; never modify backend.