@spec add(trace_state :: t(), key :: key(), value :: value()) :: t()

Application (OTel API MUST) — "Add a new key/value pair" (trace/api.md TraceState).

Prepends a new {key, value} entry per W3C §3.5 Mutating: "The new key/value pair SHOULD be added to the beginning of the list."

Returns the state unchanged when:

• the key violates W3C §3.3.1.3.1 format,
• the value violates W3C §3.3.1.3.2 format, or
• key is already present. W3C §3.5 requires that "Adding a key/value pair MUST NOT result in the same key being present multiple times" — for "update-or-add" semantics use update/3.

If adding would push the list past 32 entries, the right-most (oldest) entry is dropped per W3C §3.3.1.1: "If adding an entry would cause the tracestate list to contain more than 32 list-members the right-most list-member should be removed from the list."

@spec decode(header :: String.t()) :: t()

Application (W3C header parsing) — §3.3.1 tracestate Header Field Values.

Splits a W3C tracestate header value into {key, value} entries, collapsing duplicate keys to the last occurrence.

This function performs parsing only — it does not validate individual key/value format (W3C §3.3.1.6 grants parsers discretion on partially-parsed pairs) nor enforce the 32 list-member cap (W3C §3.3.1.1 is an "adding" rule). Validation is applied at mutation time by add/3 / update/3 per OTel api.md L294-L295. Pairs without = raise MatchError.

Used by Otel.Propagator.TextMap.TraceContext when extracting incoming requests.

@spec delete(trace_state :: t(), key :: key()) :: t()

Application (OTel API MUST) — "Delete a key/value pair" (trace/api.md TraceState).

Removes the entry for key, if present. No-op when key is absent.

@spec empty?(trace_state :: t()) :: boolean()

Application (Convenience) — empty-state predicate.

Returns whether the TraceState has no entries.

Used by Otel.Propagator.TextMap.TraceContext to skip injecting an empty tracestate header (W3C §3.3.1 L275: "SHOULD avoid sending [empty headers]").

@spec encode(trace_state :: t()) :: String.t()

Application (W3C header serialization) — §3.3.1.4 Combined Header Value.

Serializes to a W3C tracestate header value. Returns "" for an empty state.

Used by Otel.Propagator.TextMap.TraceContext when injecting outgoing requests.

@spec get(trace_state :: t(), key :: key()) :: value()

Application (OTel API MUST) — "Get value" (trace/api.md TraceState).

Returns the value associated with key, or "" (empty string) when the key is absent.

Because W3C §3.3.1.3.2 forbids empty values, a well-formed state cannot contain one — the empty-string return reliably signals "not found".

@spec new(opts :: map()) :: t()

Application (Convenience) — build a TraceState. Preferred over %TraceState{} at external call sites because t/0 is opaque.

@spec update(trace_state :: t(), key :: key(), value :: value()) :: t()

Application (OTel API MUST) — "Update an existing value" (trace/api.md TraceState).

Removes the existing entry for key and prepends a new entry with value. Per W3C §3.5: "Modified keys MUST be moved to the beginning (left) of the list."

If key is not already present, the behaviour is equivalent to add/3, including the 32-member cap (W3C §3.3.1.1) — the right-most entry is dropped to make room.

Returns the state unchanged when the key or value is invalid per W3C §3.3.1.3.1 / §3.3.1.3.2.

@spec valid_key?(key :: term()) :: boolean()

Application (W3C format predicate) — key (§3.3.1.3.1).

Returns whether key conforms to the W3C TraceState key format. See key/0 for the grammar. Returns false for any non-binary input.

@spec valid_value?(value :: term()) :: boolean()

Application (W3C format predicate) — value (§3.3.1.3.2).

Returns whether value conforms to the W3C TraceState value format. See value/0 for the grammar. Returns false for any non-binary input.