feat(groups): tree repos, hierarchy-aware RBAC, admin API

Server-side foundation for Phase-2 groups (no group-owned resources yet):

Shared types:
- GroupId, Group; App gains group_id; AppRole::{precedence,max} for
  folding the highest effective role across the membership chain.

Repos:
- group_repo: tree CRUD with reparent (ancestor-walk cycle guard under a
  coarse instance-wide structural advisory lock; slug frozen; bumps
  structure_version) and delete=RESTRICT (refuses non-empty groups).
- group_members_repo: per-(user, group) role grants, mirroring app_members.

Hierarchy-aware authz (§5.3):
- AuthzRepo gains effective_app_role / effective_group_role (default to
  direct membership / none, so the ~18 existing test stubs are untouched);
  the Postgres impl resolves each via one depth-bounded recursive CTE that
  MAXes the app's own row with every ancestor group_members row.
- can(): the Member path now folds inherited group roles, so a group_admin
  on any ancestor is implicitly app_admin beneath it. New Capability
  variants InstanceCreateGroup / Group{Read,Write,Admin}; group caps carry
  no app_id (bound API keys can't manage groups). 8 new unit tests.

Admin API:
- groups_api: group CRUD + reparent (admin at both source and destination
  parent, §5.6) + per-group members, all capability-gated.
- apps: POST /apps takes an optional parent group (default root); app
  responses carry group_id; my_role now reflects the effective role.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/manager-core/src/app_members_repo.rs

@@ -8,11 +8,17 @@
 
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
-use picloud_shared::{AdminUserId, AppId, AppRole, InstanceRole};
+use picloud_shared::{AdminUserId, AppId, AppRole, GroupId, InstanceRole, UserId};
 use sqlx::PgPool;
 
 use crate::authz::{AuthzError, AuthzRepo};
 
+/// SQL fragment ranking the three role literals by authority so a CTE can
+/// `MAX` over a mixed set of app_members + group_members rows. Shared by
+/// both effective-role queries.
+const ROLE_RANK_CTE: &str =
+    "role_rank(role, rank) AS (VALUES ('viewer', 1), ('editor', 2), ('app_admin', 3))";
+
 #[derive(Debug, thiserror::Error)]
 pub enum AppMembersRepositoryError {
     #[error("database error: {0}")]
@@ -281,13 +287,95 @@ impl AppMembersRepository for PostgresAppMembersRepository {
 impl AuthzRepo for PostgresAppMembersRepository {
     async fn membership(
         &self,
-        user_id: AdminUserId,
+        user_id: UserId,
         app_id: AppId,
     ) -> Result<Option<AppRole>, AuthzError> {
         self.find(user_id, app_id)
             .await
             .map_err(|e| AuthzError::Repo(e.to_string()))
     }
+
+    /// Highest effective role on `app_id`: one recursive CTE walks the
+    /// app's group chain (app.group_id → groups.parent_id → … → root,
+    /// depth-bounded), then `MAX`es the app's own `app_members` row with
+    /// every ancestor `group_members` row by authority rank. A single
+    /// round-trip regardless of tree depth. `None` = no grant anywhere.
+    async fn effective_app_role(
+        &self,
+        user_id: UserId,
+        app_id: AppId,
+    ) -> Result<Option<AppRole>, AuthzError> {
+        let row: Option<(String,)> = sqlx::query_as(&format!(
+            "WITH RECURSIVE ancestors AS (
+                 SELECT a.group_id AS gid, 0 AS depth FROM apps a WHERE a.id = $2
+               UNION ALL
+                 SELECT g.parent_id, anc.depth + 1
+                 FROM groups g JOIN ancestors anc ON g.id = anc.gid
+                 WHERE g.parent_id IS NOT NULL AND anc.depth < 64
+             ),
+             {ROLE_RANK_CTE}
+             SELECT eff.role
+             FROM (
+                 SELECT am.role FROM app_members am
+                 WHERE am.user_id = $1 AND am.app_id = $2
+               UNION ALL
+                 SELECT gm.role FROM group_members gm
+                 JOIN ancestors anc ON anc.gid = gm.group_id
+                 WHERE gm.user_id = $1
+             ) eff
+             JOIN role_rank rr ON rr.role = eff.role
+             ORDER BY rr.rank DESC
+             LIMIT 1"
+        ))
+        .bind(user_id.into_inner())
+        .bind(app_id.into_inner())
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(|e| AuthzError::Repo(e.to_string()))?;
+        row.map(|(role,)| {
+            AppRole::from_db_str(&role).ok_or(AuthzError::Repo(format!(
+                "invalid role {role:?} in members table"
+            )))
+        })
+        .transpose()
+    }
+
+    /// Highest effective role on a *group* node — walks the group's own
+    /// ancestor chain over `group_members`. Gates group management.
+    async fn effective_group_role(
+        &self,
+        user_id: UserId,
+        group_id: GroupId,
+    ) -> Result<Option<AppRole>, AuthzError> {
+        let row: Option<(String,)> = sqlx::query_as(&format!(
+            "WITH RECURSIVE ancestors AS (
+                 SELECT id AS gid, parent_id, 0 AS depth FROM groups WHERE id = $2
+               UNION ALL
+                 SELECT g.id, g.parent_id, anc.depth + 1
+                 FROM groups g JOIN ancestors anc ON g.id = anc.parent_id
+                 WHERE anc.depth < 64
+             ),
+             {ROLE_RANK_CTE}
+             SELECT gm.role
+             FROM group_members gm
+             JOIN ancestors anc ON anc.gid = gm.group_id
+             JOIN role_rank rr ON rr.role = gm.role
+             WHERE gm.user_id = $1
+             ORDER BY rr.rank DESC
+             LIMIT 1"
+        ))
+        .bind(user_id.into_inner())
+        .bind(group_id.into_inner())
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(|e| AuthzError::Repo(e.to_string()))?;
+        row.map(|(role,)| {
+            AppRole::from_db_str(&role).ok_or(AuthzError::Repo(format!(
+                "invalid role {role:?} in group_members table"
+            )))
+        })
+        .transpose()
+    }
 }
 
 #[derive(sqlx::FromRow)]