refactor: improve error handling and documentation in PermissionSets

- Add explicit ArgumentError for invalid permission set names with helpful message
- Soften performance claim in documentation (intended to be constant-time)
- Add tests for error handling
- Improve maintainability with guard clause for invalid inputs

lib/mv/authorization/permission_sets.ex

@@ -38,7 +38,9 @@ defmodule Mv.Authorization.PermissionSets do
 
   ## Performance
 
-  All functions are pure and compile-time. Permission lookups are < 1 microsecond.
+  All functions are pure and intended to be constant-time. Permission lookups
+  are very fast (typically < 1 microsecond in practice) as they are simple
+  pattern matches and map lookups with no database queries or external calls.
   """
 
   @type scope :: :own | :linked | :all
@@ -81,10 +83,15 @@ defmodule Mv.Authorization.PermissionSets do
       true
 
       iex> PermissionSets.get_permissions(:invalid)
-      ** (FunctionClauseError) no function clause matching
+      ** (ArgumentError) invalid permission set: :invalid. Must be one of: [:own_data, :read_only, :normal_user, :admin]
   """
   @spec get_permissions(atom()) :: permission_set()
 
+  def get_permissions(set) when set not in [:own_data, :read_only, :normal_user, :admin] do
+    raise ArgumentError,
+          "invalid permission set: #{inspect(set)}. Must be one of: #{inspect(all_permission_sets())}"
+  end
+
   def get_permissions(:own_data) do
     %{
       resources: [