@spec find_attribute(Spark.Dsl.t(), atom()) ::
  {:ok, Ash.Resource.Attribute.t()} | {:error, Exception.t()}

Find and return a named attribute in the DSL state.

@spec maybe_build_attribute(Spark.Dsl.t(), atom(), (Spark.Dsl.t() ->
                                                {:ok,
                                                 Ash.Resource.Attribute.t()})) ::
  {:ok, Spark.Dsl.t()}

Build an attribute if not present.

@spec oauth2_strategy_warnings(
  struct(),
  Spark.Dsl.t() | map()
) :: :ok | {:warn, [String.t()]}

Collect compile-time warnings for an OAuth2/OIDC strategy.

Returns {:warn, messages} (so the configuration still compiles) for the following safety issues:

• No identity_resource is configured. Matching a local user by their email address (or any other provider-supplied claim) is not safe: per the OpenID Connect Core specification only the iss/sub claims uniquely and stably identify an end-user, and the identity resource is where those are persisted. This will become a hard requirement in a future release.

• The provider's email_verified claim is not trusted (trust_email_verified? is false) and no confirmation add-on is configured. Accounts created via this strategy would carry an unverified email address with no way to verify ownership.

@spec persisted_option(Spark.Dsl.t(), atom()) ::
  {:ok, any()} | {:error, {:unknown_persisted, atom()}}

Find and return a persisted option in the DSL state.

@spec validate_behaviour(module(), module()) :: :ok | {:error, Exception.t()}

Ensure that the named module implements a specific behaviour.

@spec validate_extension(Spark.Dsl.t(), module()) :: :ok | {:error, Exception.t()}

Validates that extension is present on the resource.

@spec validate_field_in_values(map(), any(), [any()]) :: :ok | {:error, String.t()}

Given a map validate that the provided field is one of the values provided.

@spec validate_field_with(map(), field, (any() -> boolean()), message) ::
  :ok | {:error, message}
when field: any(), message: any()

Given a map, validate that the provided field predicate returns true for the value.

Validate that a "secret" field is configured correctly.

@spec validate_token_generation_enabled(Spark.Dsl.t(), binary()) ::
  :ok | {:error, Exception.t()}

Ensure that token generation is enabled for the resource.

@spec warn_if_data_layer_cannot_lock(Ash.Resource.t(), String.t()) :: :ok

Emit a Logger.warning if the given resource's data layer does not support the {:lock, :for_update} capability.

Used by verifiers for resources that AshAuthentication tries to lock at runtime (the token resource, the audit log resource, the recovery code resource). On data layers that don't support locking the lock is skipped at runtime — but races between concurrent processes are no longer prevented, which the user should know about.

Returns :ok either way; this is advisory, not a hard failure.