@spec all(atom()) :: %{required(String.t()) => term()}

Return the merged map (config + runtime) for a kind.

@spec kinds() :: [atom()]

List the known registry kinds.

@spec list(atom()) :: [String.t()]

Sorted list of registered names for a kind.

@spec lookup(atom(), String.t()) :: term() | nil

Look up a value by kind + name. Returns nil if not registered. Runtime overrides win over config.

@spec lookup!(atom(), String.t()) :: term()

Look up a value by kind + name. Raises if not registered.

@spec register(atom(), String.t(), term()) :: :ok | {:error, term()}

Generic register — kind must be one of [:profile, :tool, :schema, :router, :round, :sub_council, :input_mapper, :council].

@spec register_council(String.t(), map()) :: :ok

Register a routable council under name. Used by CouncilEx.AutoCouncil to discover councils a strategy can pick from.

The value should be a map with at least:

%{
  council:    module() | CouncilEx.DynamicCouncil.t(),
  desc:       String.t(),       # human-readable description (used by LLM strategies)
  match:      Regex.t() | (binary() -> boolean()) | nil,   # optional, used by Rules
  vector:     [float()] | nil,  # optional, used by Embedding
  tags:       [atom()] | nil,   # optional, free-form
  providers:  MapSet.t(atom()) | nil   # cached at registration; see below
}

Strategies may ignore fields they don't need. Only :council is mandatory.

At registration time the registry computes the council's provider set (via CouncilEx.AutoCouncil.Providers.used/1) and stashes it under :providers. This cache backs provider_check: true so the resolver doesn't re-walk the council on every route.

Cache invalidation

Re-register to invalidate. The cache only goes stale if the underlying council's member providers change and the entry isn't re-registered. Static councils carry their own __providers__/0, so the cache is effectively free; dynamic councils get a single to_spec/1 walk per registration.

Pass providers: nil (or any explicit MapSet) to override the auto-computed value.

@spec register_input_mapper(String.t(), (term() -> term())) :: :ok

Register an input mapper under name. The value must be a 1-arity function (typically a remote capture like &MyApp.Mappers.to_seo_input/1) used by dynamic sub-council members to project the parent input.

@spec register_profile(String.t(), term()) :: :ok

Register a profile module (or struct) at runtime under name.

@spec register_round(String.t(), module()) :: :ok

Register a round module at runtime under name.

@spec register_router(String.t(), module()) :: :ok

Register a router module at runtime under name.

@spec register_schema(String.t(), module() | map()) :: :ok

Register an output schema (Ecto module or JSON Schema map) under name.

@spec register_sub_council(String.t(), module() | CouncilEx.DynamicCouncil.t()) :: :ok

Register a sub-council target at runtime under name. Accepts either a static council module or a %CouncilEx.DynamicCouncil{} struct. Used by dynamic councils that reference sub-councils by string name.

@spec register_tool(String.t(), module()) :: :ok

Register a tool module at runtime under name.

@spec reset_runtime() :: :ok | {:error, term()}

Wipe ALL runtime registrations. Config entries unaffected.

@spec unregister(atom(), String.t()) :: :ok | {:error, term()}

Remove a runtime registration. Has no effect on config-defined entries.