@spec add_span(String.t(), AITrace.Span.t()) :: :ok | {:error, map()}

Adds a span to a trace.

@spec authoritative_evidence?() :: false

Returns false because collector state is in-memory working state only.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear() :: :ok | {:error, :collector_not_started}

Clears all traces from the supervised collector.

@spec evidence_posture() :: map()

Describes the collector evidence posture for release and incident proof.

@spec get_trace(String.t()) :: AITrace.Trace.t() | nil

Retrieves a trace by its trace_id.

@spec new_trace(
  String.t(),
  keyword()
) :: AITrace.Trace.t()

Creates a new trace owner and stores the trace.

@spec remove_trace(String.t()) :: :ok

Removes a trace owner from the collector.

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the collector supervisor.

@spec stats(String.t()) :: map() | nil

Returns per-trace collector stats.

@spec update_span(String.t(), String.t(), (AITrace.Span.t() -> AITrace.Span.t())) ::
  :ok

Updates a span within a trace.

@spec update_trace(String.t(), (AITrace.Trace.t() -> AITrace.Trace.t())) :: :ok

Updates a trace within its supervised owner.