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/picloud/src/lib.rs

@@ -12,26 +12,28 @@ use picloud_executor_core::{Engine, Limits};
 use picloud_manager_core::{
     admin_router, admins_router, api_keys_router, app_members_router, apply_router, apps_api,
     apps_router, attach_principal_if_present, auth_router, compile_routes, dead_letters_router,
-    dev_emails_router, email_inbound_router, files_admin_router, kv_admin_router, migrations,
-    require_authenticated, route_admin_router, secrets_router, topics_router, triggers_router,
-    AbandonedRepo, AdminPrincipalResolver, AdminSessionRepository, AdminState, AdminUserRepository,
-    AdminsState, ApiKeyRepository, ApiKeysState, AppDomainRepository, AppMembersRepository,
-    AppMembersState, AppRepository, ApplyService, AppsState, AuthState, AuthzRepo, DeadLetterRepo,
-    DeadLettersState, DevEmailState, Dispatcher, DocsServiceImpl, EmailInboundState,
-    EmailServiceImpl, FilesAdminState, FilesConfig, FilesServiceImpl, FsFilesRepo, HttpConfig,
-    HttpServiceImpl, InboundNonceDedup, KvAdminState, KvServiceImpl, OutboxEventEmitter,
-    OutboxRepo, PostgresAbandonedRepo, PostgresAdminSessionRepository, PostgresAdminUserRepository,
+    dev_emails_router, email_inbound_router, files_admin_router, groups_router, kv_admin_router,
+    migrations, require_authenticated, route_admin_router, secrets_router, topics_router,
+    triggers_router, AbandonedRepo, AdminPrincipalResolver, AdminSessionRepository, AdminState,
+    AdminUserRepository, AdminsState, ApiKeyRepository, ApiKeysState, AppDomainRepository,
+    AppMembersRepository, AppMembersState, AppRepository, ApplyService, AppsState, AuthState,
+    AuthzRepo, DeadLetterRepo, DeadLettersState, DevEmailState, Dispatcher, DocsServiceImpl,
+    EmailInboundState, EmailServiceImpl, FilesAdminState, FilesConfig, FilesServiceImpl,
+    FsFilesRepo, GroupMembersRepository, GroupRepository, GroupsState, HttpConfig, HttpServiceImpl,
+    InboundNonceDedup, KvAdminState, KvServiceImpl, OutboxEventEmitter, OutboxRepo,
+    PostgresAbandonedRepo, PostgresAdminSessionRepository, PostgresAdminUserRepository,
     PostgresApiKeyRepository, PostgresAppDomainRepository, PostgresAppMembersRepository,
     PostgresAppRepository, PostgresAppSecretsRepo, PostgresAppUserInvitationRepo,
     PostgresAppUserPasswordResetRepo, PostgresAppUserRepository, PostgresAppUserRoleRepo,
     PostgresAppUserSessionRepository, PostgresAppUserVerificationRepo, PostgresDeadLetterRepo,
     PostgresDeadLetterService, PostgresDocsRepo, PostgresExecutionLogRepository,
-    PostgresExecutionLogSink, PostgresKvRepo, PostgresOutboxRepo, PostgresPubsubRepo,
-    PostgresRouteRepository, PostgresScriptRepository, PostgresSecretsRepo, PostgresTopicRepo,
-    PostgresTriggerRepo, PrincipalResolver, PubsubServiceImpl, RealtimeAuthorityImpl, RepoResolver,
-    RouteAdminState, RouteRepository, SandboxCeiling, ScriptRepository, SecretsConfig,
-    SecretsServiceImpl, SecretsState, SubscriberTokenConfig, TopicRepo, TopicsState, TriggerConfig,
-    TriggerRepo, TriggersState, UsersServiceConfig, UsersServiceImpl,
+    PostgresExecutionLogSink, PostgresGroupMembersRepository, PostgresGroupRepository,
+    PostgresKvRepo, PostgresOutboxRepo, PostgresPubsubRepo, PostgresRouteRepository,
+    PostgresScriptRepository, PostgresSecretsRepo, PostgresTopicRepo, PostgresTriggerRepo,
+    PrincipalResolver, PubsubServiceImpl, RealtimeAuthorityImpl, RepoResolver, RouteAdminState,
+    RouteRepository, SandboxCeiling, ScriptRepository, SecretsConfig, SecretsServiceImpl,
+    SecretsState, SubscriberTokenConfig, TopicRepo, TopicsState, TriggerConfig, TriggerRepo,
+    TriggersState, UsersServiceConfig, UsersServiceImpl,
 };
 use picloud_orchestrator_core::realtime::DEFAULT_GC_INTERVAL_SECS;
 use picloud_orchestrator_core::routing::{AppDomainTable, RouteTable};
@@ -109,6 +111,10 @@ pub async fn build_app(
     let log_sink: Arc<dyn ExecutionLogSink> = Arc::new(PostgresExecutionLogSink::new(pool.clone()));
     let route_repo = Arc::new(PostgresRouteRepository::new(pool.clone()));
     let apps_repo: Arc<dyn AppRepository> = Arc::new(PostgresAppRepository::new(pool.clone()));
+    let groups_repo: Arc<dyn GroupRepository> =
+        Arc::new(PostgresGroupRepository::new(pool.clone()));
+    let group_members_repo: Arc<dyn GroupMembersRepository> =
+        Arc::new(PostgresGroupMembersRepository::new(pool.clone()));
     let domains_repo: Arc<dyn AppDomainRepository> =
         Arc::new(PostgresAppDomainRepository::new(pool.clone()));
     // The Postgres app_members repo implements both `AppMembersRepository`
@@ -513,6 +519,7 @@ pub async fn build_app(
         routes: route_repo,
         domain_table: app_domain_table.clone(),
         authz: authz.clone(),
+        groups: groups_repo.clone(),
     };
 
     // Audit 2026-06-11 H-B1 — login DoS defenses. PICLOUD_LOGIN_ARGON2_PARALLELISM
@@ -552,6 +559,13 @@ pub async fn build_app(
         members,
         authz: authz.clone(),
     };
+    let groups_state = GroupsState {
+        groups: groups_repo.clone(),
+        group_members: group_members_repo.clone(),
+        apps: apps_state.apps.clone(),
+        users: auth.users.clone(),
+        authz: authz.clone(),
+    };
     let app_users_admin_state = picloud_manager_core::AppUsersState {
         apps: apps_state.apps.clone(),
         authz: authz.clone(),
@@ -574,6 +588,7 @@ pub async fn build_app(
         .merge(admins_router(admins_state))
         .merge(apps_router(apps_state))
         .merge(app_members_router(app_members_state))
+        .merge(groups_router(groups_state))
         .merge(picloud_manager_core::app_users_router(
             app_users_admin_state,
         ))