# Configuration

Pass options to `use MaxoAdapt`:

```elixir
use MaxoAdapt,
  mode: :compile,
  default: MyApp.PostgreSQL,
  error: :storage_not_configured,
  log: :debug,
  validate: true
```

Unknown options and invalid values raise a compile error at the `use` call.

## Options

- `:mode` — dispatch strategy. Default: `:compile`. Accepted values:
  - `:compile` — direct delegates regenerated by runtime `configure/1`;
  - `:get_compiled` — direct delegates fixed through `Application.compile_env/3`;
  - `:get_env` — `Application.get_env/3` lookup on every call;
  - `:get_dict` — process-local lookup with live-ancestor inheritance.

- `:default` — implementation used before explicit configuration. Default: `nil`.

- `:error` — atom returned as `{:error, reason}` when no implementation exists, or `:raise` to raise `RuntimeError`. Default: an atom derived from the facade module, such as `:session_repo_not_configured`.

- `:log` — mutable-configuration log level. Accepted values: `:debug`, `:info`, `:notice`, or `false`. Default: `:debug`.

- `:validate` — validate required callback name/arity pairs before mutable configuration and loaded compile-time configuration. Default: `true`. Set to `false` only when intentionally installing a partial implementation.

- `:random` — preserve the historical one-element `Enum.random/1` wrapper around unconfigured results. This prevents Dialyzer/compiler analysis from treating a pre-configuration fallback as the only possible callback result. Default: `true`.

- `:app` — application used by `:get_compiled` and `:get_env`. Default: `:maxo_adapt`.

- `:key` — application-environment key, or process-dictionary key for `:get_dict`. Default: the underscored full facade module name.

## Project-wide defaults

The mode used when `:mode` is omitted can be configured while adapter modules compile:

```elixir
config :maxo_adapt, default_mode: :get_dict
```

This is useful in `config/test.exs` for process-isolated test adapters. Generator diagnostics use `config :maxo_adapt, debug: true`; see the debugging guide.

## Application configuration

For `:get_compiled`:

```elixir
# config/config.exs
config :my_app, session_repo: MyApp.SessionRepo.PostgreSQL

defmodule MyApp.SessionRepo do
  use MaxoAdapt,
    mode: :get_compiled,
    app: :my_app,
    key: :session_repo

  behaviour do
    @callback get(binary()) :: {:ok, term()} | {:error, atom()}
  end
end
```

The configured module must be available when the facade is compiled for eager validation. Forward references in the same compilation unit remain supported and are checked by normal generated calls when loaded.

`configure/1` is available at runtime in `:compile`, `:get_env`, and `:get_dict` modes. Calling it in `:get_compiled` mode raises.

## Optional callbacks

Callbacks listed with `@optional_callbacks` remain part of the Elixir behaviour but are omitted from required MaxoAdapt facade generation and validation, because MaxoAdapt cannot invent a safe fallback for an optional operation.