Tracking: OpenTelemetry spec-compliance audit — API fixes & documented gaps

[michaelbushe]

Why a GitHub issue and not Slack? Coordination like this would normally live in an OpenTelemetry channel on the CNCF Slack. There isn't one for Dart/Flutter yet, so this issue is its interim public home until the Dart & Flutter SIG is approved and the channel exists. Everything stays public either way, per CNCF norms.

Tracking hub for the current wave of OpenTelemetry specification-compliance work on the Dart OTel reference API (dartastic_opentelemetry_api).

Each item was found by auditing the API against the OpenTelemetry specification (and W3C Trace Context) and follows the same TDD shape: a first commit pins the contract with red tests that quote the spec clause, a second turns them green — or, where the fix needs design, a commit that skips the red tests behind a linked issue so CI stays green until the fix lands.

This is the public coordination point for the batch. Reviews, spec-interpretation debate, and "did we read the spec right?" questions are all welcome here or on the individual PRs.

Fixes (behavior changes) — ready for review

• fix: Baggage spec compliance — accept empty values, never throw #36 — Baggage: accept empty values, never throw. baggage/api.md + error-handling.md: values are any valid UTF-8 string (the empty string included), and API methods must not throw when misused. 8 contracts red→green.
• fix: TraceState spec compliance — ignore invalid input, never throw #37 — TraceState: ignore invalid input, never throw. trace/api.md + error-handling.md: mutating operations must validate input and must not return invalid data or throw — TraceState.put now warns and ignores instead of throwing ArgumentError. 5 contracts red→green.
• fix: provider accessors use spec-mandated safe defaults, never throw #39 — Provider accessors: spec-mandated safe defaults, never throw. trace/api.md + error-handling.md: tracerProvider('') / meterProvider('') / loggerProvider('') must return a working default rather than null-or-throw. 6 contracts red→green.

Documented gaps (tests only, skipped) — need a fix / design

• test: document no-SDK span behavior spec violations (#40) #41 — documents no-SDK span behavior violations, pinning them red then skipping until the fix lands (fix: No-SDK trace behavior violates trace/api.md: random IDs, recording spans, no SpanContext wrapper #40): parentless spans get random IDs, spans report isRecording == true, and there's no all-zero SpanContext wrapper.
• test: document missing global propagator API (#42) #43 — documents the missing global propagator API, pinned red then skipped until the design lands (fix: No global propagator API — context/api-propagators.md requires get/set with no-op default #42): no global get/set and no no-op TextMapPropagator, so instrumentation can't obtain "the" propagator.

Fix / design issues behind the skips

• No-SDK trace behavior violates trace/api.md: random IDs, recording spans, no SpanContext wrapper #40 — No-SDK trace behavior violates trace/api.md: random IDs, recording spans, no SpanContext wrapper
• No global propagator API — context/api-propagators.md requires get/set with no-op default #42 — No global propagator API — context/api-propagators.md requires get/set with a no-op default

Recently landed

• fix: validate tracestate tenant/system keys per W3C grammar #38 — W3C tracestate tenant/system key grammar: leading-digit tenants accepted, tenant-id/system-id length caps (241/14). Same audit.

Coordination

All discussion is public, per CNCF norms. This work is part of standing up the Dart & Flutter SIG; once the SIG's CNCF Slack channel and community-calendar meeting exist, they'll be linked here.

/cc @harshitt13 @kevmoo @muhammadkamel @rohit482 @cnbleu @yuzurihaaa @robert-northmind @benjaben @danexello