§22 S4: scope-role invitation backend + capability flags (@S4 C.2)

The Owner-only scope-role grant surface (Part E S4 / Part C.2). An Owner
grants {owner, contributor} at a scope their reach covers — the project or
one collection within it — to an existing account looked up by email; the
grant writes a `memberships` row immediately and §15-notifies the grantee
(direct grant, no accept round-trip — the C.2 scenarios name existing
accounts and write the row directly).

- auth.can_invite_at_project / can_invite_at_collection — the Owner-reach
  invite gates (is_project_superuser / is_collection_superuser).
- memberships.py — grant (with the C.2.6 broader-supersedes-narrower prune,
  preserving a stronger child grant — no negative override), revoke, list,
  user_by_email.
- api_memberships.py — GET/POST/DELETE /api/projects/:id/members, the single
  POST keying on optional collection_id so the invite UI's one control maps
  to one endpoint; reach bounded by the inviter's Owner reach (C.2.3);
  contributors refused (C.2.4); a pending grantee's row is recorded but
  confers no write (C.2.7, the §6 floor).
- notify.notify_scope_role_granted + render_summary — the §15 personal-direct
  notification naming the project and role.
- api_collections — surface viewer capabilities (can_create_collection,
  can_invite, can_contribute, role) on the project/collection GETs to drive
  the C.3 role-aware empty states.

Acceptance: test_s4_invitations_vertical.py covers C.2.1–C.2.7 over the HTTP
surface + resolver, plus the C.3 (@S4) capability flags. Full suite green
(504 passed).

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

backend/app/api_collections.py

@@ -41,6 +41,26 @@ class CreateCollectionBody(BaseModel):
     initial_state: str | None = None
 
 
+def _project_viewer_caps(viewer: Any, project_id: str) -> dict[str, Any]:
+    """§22 S4: the viewer's project-grain capabilities for role-aware UI — may
+    they create a collection, may they manage membership (invite), and their
+    project role. `role` maps the §22.6 legacy strings back to the unified
+    `{owner, contributor}` vocabulary the frontend speaks."""
+    legacy = auth.project_member_role(viewer, project_id)
+    role = None
+    if viewer is not None and viewer.role in ("owner", "admin"):
+        role = "owner"
+    elif legacy == "project_admin":
+        role = "owner"
+    elif legacy == "project_contributor":
+        role = "contributor"
+    return {
+        "can_create_collection": auth.can_create_collection(viewer, project_id),
+        "can_invite": auth.can_invite_at_project(viewer, project_id),
+        "role": role,
+    }
+
+
 def make_router(config: Config, gitea: Gitea, bot: Bot) -> APIRouter:
     router = APIRouter()
 
@@ -57,7 +77,10 @@ def make_router(config: Config, gitea: Gitea, bot: Bot) -> APIRouter:
             for c in collections_mod.list_collections(project_id, include_unlisted=True)
             if c["visibility"] != "unlisted" and auth.can_read_collection(viewer, c["id"])
         ]
-        return {"items": items}
+        # §22 S4: surface the viewer's project-level capabilities so the
+        # directory can render role-aware affordances (the create-first-
+        # collection CTA, the invite control) without a second round-trip.
+        return {"items": items, "viewer": _project_viewer_caps(viewer, project_id)}
 
     @router.get("/api/projects/{project_id}/collections/{collection_id}")
     async def get_col(project_id: str, collection_id: str, request: Request) -> dict[str, Any]:
@@ -68,6 +91,14 @@ def make_router(config: Config, gitea: Gitea, bot: Bot) -> APIRouter:
             raise HTTPException(404, "Not found")
         # §22.5 (S3): a hidden/gated collection 404s a non-scope-role viewer.
         auth.require_collection_readable(viewer, collection_id)
+        # §22 S4: the viewer's collection-level capabilities drive the
+        # propose-first empty state and the collection invite control.
+        col = dict(col)
+        col["viewer"] = {
+            "can_contribute": auth.can_contribute_in_collection(viewer, collection_id),
+            "can_invite": auth.can_invite_at_collection(viewer, collection_id),
+            "role": auth.effective_scope_role(viewer, collection_id),
+        }
         return col
 
     @router.post("/api/projects/{project_id}/collections")