@spec default_source() :: Lotus.Source.Adapter.t()

Returns the default source as an %Adapter{} struct.

@spec editor_config(Lotus.Source.Adapter.t() | String.t()) :: map()

Return the editor configuration for a source.

@spec example_query(
  Lotus.Source.Adapter.t() | String.t(),
  String.t(),
  String.t() | nil
) :: String.t()

Return an example query string suitable for placeholder text.

@spec get_source!(String.t()) :: Lotus.Source.Adapter.t()

Gets a source adapter by name. Raises if not found.

@spec hierarchy_label(Lotus.Source.Adapter.t() | String.t()) :: String.t()

Return the human-readable label for the top-level hierarchy in a source.

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

Tells the configured resolver to drop what it holds for name.

Call this after a source is edited, paused or removed at runtime, so the next resolve!/2 rebuilds its adapter, then call reconcile/0 so its processes follow. The drop is applied on this node and relayed to every other node of the cluster through Lotus.Notifier. A resolver that does not implement Lotus.Source.Resolver.invalidate/1 has nothing to drop and this is a no-op.

@spec limit_query(
  Lotus.Source.Adapter.t() | String.t(),
  Lotus.Query.Statement.t(),
  pos_integer()
) ::
  Lotus.Query.Statement.t()

Wrap a statement with a limit clause using the source's syntax.

@spec list_sources() :: [Lotus.Source.Adapter.t()]

Lists all configured source adapters.

@spec prepare_for_analysis(
  Lotus.Source.Adapter.t() | String.t(),
  Lotus.Query.Statement.t()
) ::
  {:ok, Lotus.Query.Statement.t()} | {:error, term()}

Ask the adapter to resolve a statement into a form suitable for optimization analysis (e.g. neutralizing {{var}} placeholders and stripping [[...]] optional clauses so the engine's EXPLAIN / profile endpoint can parse it).

Returns {:error, :unsupported} when the adapter does not implement prepare_for_analysis/2 — callers should treat that as "skip optimization for this source".

@spec query_language(Lotus.Source.Adapter.t() | String.t()) :: String.t()

Return the query language identifier for a source.

@spec reconcile() :: {:ok, Lotus.Source.Supervisor.report()} | {:error, term()}

Starts and stops the processes adapters own so they match the resolver's sources.

Call this after a source is added, edited, paused or removed at runtime. Boot runs the first reconcile. The call reconciles this node and returns its report, then tells every other node of the cluster to reconcile too through Lotus.Notifier; those reconciles run in the background and their reports are logged. See Lotus.Source.Supervisor for what a reconcile does and what it returns.

@spec resolve!(nil | String.t() | module(), nil | String.t() | module()) ::
  Lotus.Source.Adapter.t()

Resolve to an %Adapter{} struct.

Accepts:

• source_opt — configured name (string) or source module (atom) or nil
• q_source — query's stored source (string or module) or nil

Falls back to the default source. Raises on resolution failure.

@spec source_type(Lotus.Source.Adapter.t() | module() | String.t()) ::
  Lotus.Source.Adapter.source_type()

Detect the source type from an adapter, repository module, or name.

@spec supported_filter_operators(Lotus.Source.Adapter.t() | String.t()) :: [atom()]

Return the Lotus.Query.Filter operators this source's adapter supports.

UIs that expose a filter operator dropdown should read this list and gate the options per source — attempting to use an operator outside the declared list raises Lotus.UnsupportedOperatorError when filters are applied.

@spec supports_feature?(Lotus.Source.Adapter.t() | String.t() | module(), atom()) ::
  boolean()

Whether a source supports a specific feature.

Accepts an %Adapter{} struct or a source name/repo module (resolved to adapter).