@spec clear() :: :ok

Clears the trace context from the process dictionary.

@spec ensure_from_signal(Jido.Signal.t()) :: {Jido.Signal.t(), map()}

Ensures trace context exists from a signal.

If the signal has trace data, stores it in the process dictionary. If not, creates a new root trace and stores it.

Returns {traced_signal, trace_context} where traced_signal has trace data attached.

@spec get() :: map() | nil

Gets the current trace context, or nil if not set.

@spec propagate_to(Jido.Signal.t(), String.t()) ::
  {:ok, Jido.Signal.t()} | {:error, :no_trace_context}

Propagates trace context to a new signal.

Creates a child span with:

• Same trace_id as current context
• New span_id for the child signal
• parent_span_id set to current span_id
• causation_id set to the provided causation_id (typically input_signal.id)

Returns {:ok, traced_signal} or {:error, :no_trace_context}.

@spec set_from_signal(Jido.Signal.t()) :: :ok | {:error, :no_trace}

Sets trace context from a signal's existing trace data.

Returns :ok if trace data was found and stored, {:error, :no_trace} otherwise.

@spec to_telemetry_metadata() :: map()

Returns the current trace context as telemetry metadata.

Returns an empty map if no context is set. Keys are prefixed with jido_ for telemetry namespace.