@spec capabilities(module()) :: [atom()]

Returns messaging content capabilities for an adapter.

Adapters may expose either:

• content_capabilities/0 (preferred), or
• capabilities/0 list (legacy), or
• Jido.Chat.Adapter.capabilities/1 matrix (fallback inference).

@spec channel_type(module()) :: atom()

Returns adapter channel type, falling back to module name inference.

@spec classify_failure(term()) :: failure_class()

Classifies adapter failures into retry/degrade/crash classes.

@spec delete_ingress_subscription(module(), String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Deletes an adapter-scoped provider ingress subscription.

@spec edit_media(
  module(),
  String.t() | integer(),
  String.t() | integer(),
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Edits media payload through adapter-native or replacement behavior.

Preference order:

1. adapter-native edit_media/4
2. replacement edit: send the new media and delete the old message

@spec edit_message(
  module(),
  String.t() | integer(),
  String.t() | integer(),
  String.t(),
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Normalizes outbound edit through canonical adapter boundary.

@spec ensure_ingress_subscription(module(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Ensures an adapter-scoped provider ingress subscription.

The callback is intentionally optional and lives outside the core Jido.Chat.Adapter behaviour. Adapter packages can implement ensure_ingress_subscription/2 when the provider supports control-plane webhook/event subscription provisioning.

@spec failure_disposition(failure_class() | map() | term()) :: failure_disposition()

Maps failure class to runtime disposition.

@spec list_ingress_subscriptions(module(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Lists adapter-scoped provider ingress subscriptions.

@spec listener_child_specs(module(), String.t(), keyword()) ::
  {:ok, [Supervisor.child_spec()]} | {:error, map()}

Returns listener child specs for an adapter, defaulting to no listeners.

Runtime passes a standard listener context in opts:

• :instance_module - messaging runtime instance module
• :bridge_id - bridge identifier
• :bridge_config - resolved bridge config
• :settings - bridge config opts map
• :ingress - normalized ingress settings map
• :sink_mfa - sink callback MFA {module, function, base_args}

@spec sanitize_outbound(module(), term(), keyword()) ::
  {:ok, term()} | {:ok, term(), map()} | {:error, term()}

Sanitizes outbound payload when adapter provides custom sanitize callback.

Default is passthrough {:ok, outbound}.

@spec send_media(module(), String.t() | integer(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Sends media payload through the canonical adapter boundary.

Preference order:

1. adapter-native send_media/3
2. canonical post_message/4 or send_file/4 fallback through Jido.Chat.Adapter

@spec send_message(module(), String.t() | integer(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Normalizes outbound send through canonical adapter boundary.

@spec supports?(module(), atom()) :: boolean()

Checks whether adapter supports a messaging capability.

@spec verify_sender(module(), map(), map()) :: :ok | {:ok, map()} | {:error, term()}

Verifies inbound sender when adapter supports verification.

Default is permissive :ok.