@spec correlation_id(Jido.Signal.t() | map() | nil) :: String.t() | nil

Extracts the best available request/call correlation identifier from signal data.

@spec error_envelope(atom(), String.t(), map(), boolean()) :: error_envelope()

Builds a normalized AI runtime error envelope.

Prefer Jido.AI.Error.error_envelope/4 for new runtime code.

@spec normalize_error(term(), atom(), String.t(), map()) :: error_envelope()

Normalizes arbitrary error values into the canonical AI error envelope.

Prefer Jido.AI.Error.normalize/4 for new runtime code.

@spec normalize_result(term(), atom(), String.t()) ::
  {:ok, term(), [term()]} | {:error, error_envelope(), [term()]}

Ensures result payloads use {:ok, term, effects} or {:error, reason, effects} tuples.

Prefer Jido.AI.Error.normalize_result/3 for new runtime code.

@spec retryable?(term()) :: boolean()

Returns whether a result or error should be treated as retryable by runtime policy.

Prefer Jido.AI.Error.retryable?/1 for new runtime code.

@spec sanitize_delta(term(), non_neg_integer()) :: String.t()

Sanitizes streaming deltas by removing control bytes and truncating payload size.