@spec adapter() :: module()

Returns the currently configured storage adapter.

The local filesystem adapter is used when no adapter is configured.

@spec backend_name(module()) :: String.t()

Returns the stable persisted name for a storage adapter.

@spec config() :: config()

Returns the resolved application storage configuration.

@spec delete(
  String.t(),
  keyword()
) :: :ok | {:error, error_reason()}

Deletes a storage key through its owning backend.

Accepts the same :storage_backend and :config options as get/2.

@spec get(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, error_reason()}

Reads a storage key through its owning backend.

Use :storage_backend to select a named historical backend and :config to overlay adapter configuration for this operation.

@spec put(String.t(), binary(), String.t()) ::
  {:ok, String.t()} | {:error, error_reason()}

Persists document contents through the configured adapter and returns the adapter-specific storage key to save with the document row.

@spec read(Aludel.Evals.TestCaseDocument.t()) ::
  {:ok, binary()} | {:error, error_reason()}

Reads the contents associated with a test case document.

The document's persisted backend name is honored, allowing records created before a backend switch to remain readable. Documents without storage metadata return {:error, :missing_document_data}.

@spec resolve_backend(String.t() | nil) ::
  {:ok, module()} | {:error, :unknown_storage_backend}

Resolves a persisted backend name to a storage adapter module.

nil selects the active adapter. Unknown names return {:error, :unknown_storage_backend} without creating atoms.

@spec storage_key(Ecto.UUID.t(), String.t()) :: String.t()

Builds a namespaced storage key for an uploaded document.

Directory components are removed from the filename and unsupported characters are replaced with underscores.