feat(l1): enforce seat limits on invite, accept-invite, role-change

For engineer + l1_tech roles, check_seat_available is called at each
mutation point. Returns 402 Payment Required with structured detail
{code: 'seat_limit_exceeded', role, current, limit, upgrade_url} when
seats are full. Grandfathering: existing over-seated accounts keep
existing users; only new mutations are blocked.

Also updates AccountInviteCreate and AccountRoleUpdate schemas to
accept l1_tech as a valid role value.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/app/api/endpoints/accounts.py

@@ -24,10 +24,50 @@ from app.schemas.subscription import SubscriptionResponse, PlanLimitsResponse, U
 from app.schemas.user import UserResponse, AccountRoleUpdate
 from app.core.security import verify_password
 from app.api.deps import get_current_active_user, require_account_owner
+from app.services.seat_enforcement import check_seat_available
+
+_SEAT_CHECKED_ROLES = frozenset({"engineer", "l1_tech"})
 
 router = APIRouter(prefix="/accounts", tags=["accounts"])
 
 
+async def _load_account(db: AsyncSession, account_id: UUID) -> Account:
+    """Load an Account by id; raises 404 if missing."""
+    result = await db.execute(select(Account).where(Account.id == account_id))
+    account = result.scalar_one_or_none()
+    if account is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Account not found")
+    return account
+
+
+async def _enforce_seat_limit(db: AsyncSession, account_id: UUID, role: str) -> None:
+    """Raise HTTP 402 if the account has no capacity for the given role.
+
+    Only fires for seat-counted roles (engineer, l1_tech).
+    Accounts without a subscription (free / pre-billing) are not blocked.
+    Grandfathering: if current > limit, existing users keep access; this
+    helper only blocks new additions.
+    """
+    if role not in _SEAT_CHECKED_ROLES:
+        return
+    sub = await get_account_subscription(account_id, db)
+    if sub is None:
+        return  # no subscription → no enforcement
+    account = await _load_account(db, account_id)
+    seat_result = await check_seat_available(account, sub, role, db)
+    if not seat_result.available:
+        raise HTTPException(
+            status_code=status.HTTP_402_PAYMENT_REQUIRED,
+            detail={
+                "code": "seat_limit_exceeded",
+                "role": seat_result.role,
+                "current": seat_result.current,
+                "limit": seat_result.limit,
+                "upgrade_url": "/account/billing",
+            },
+        )
+
+
 @router.get("/me", response_model=AccountResponse)
 async def get_my_account(
     db: Annotated[AsyncSession, Depends(get_db)],
@@ -141,6 +181,11 @@ async def update_member_role(
             detail="Cannot change your own role"
         )
 
+    # Seat enforcement: check capacity before promoting to a seat-counted role.
+    # Demotions (engineer/l1_tech → viewer) and lateral moves skip the check.
+    if data.account_role != user.account_role:
+        await _enforce_seat_limit(db, current_user.account_id, data.account_role)
+
     user.account_role = data.account_role
     await db.commit()
     await db.refresh(user)
@@ -261,6 +306,9 @@ async def create_invite(
     current_user: Annotated[User, Depends(require_account_owner)]
 ):
     """Create an invite to join this account (owner only). Sends invite email."""
+    # Seat enforcement: block invite if the target role is at capacity.
+    await _enforce_seat_limit(db, current_user.account_id, data.role)
+
     code = secrets.token_urlsafe(16)
 
     expires_at = None
@@ -317,6 +365,10 @@ async def create_invites_bulk(
     failed: list[dict] = []
     for invite_data in payload.invites:
         try:
+            # Seat enforcement per invite row — 402 bubbles as an HTTPException
+            # which is caught below and recorded in `failed`.
+            await _enforce_seat_limit(db, current_user.account_id, invite_data.role)
+
             code = secrets.token_urlsafe(16)
             expires_at = None
             if invite_data.expires_in_days:

backend/app/api/endpoints/auth.py

@@ -289,6 +289,33 @@ async def register(
                     detail="Invite code has expired"
                 )
 
+    # Seat enforcement: re-check at accept time (race-condition guard).
+    # Fires only when an account invite is being accepted and the target role
+    # is seat-counted (engineer, l1_tech). Accounts without a subscription
+    # (free / pre-billing) are not blocked.
+    if account_invite_record and account_invite_record.role in ("engineer", "l1_tech"):
+        from app.core.subscriptions import get_account_subscription
+        from app.services.seat_enforcement import check_seat_available
+        from app.models.account import Account as _Account
+        sub = await get_account_subscription(account_invite_record.account_id, db)
+        if sub is not None:
+            acct_result = await db.execute(
+                select(_Account).where(_Account.id == account_invite_record.account_id)
+            )
+            acct = acct_result.scalar_one()
+            seat_result = await check_seat_available(acct, sub, account_invite_record.role, db)
+            if not seat_result.available:
+                raise HTTPException(
+                    status_code=status.HTTP_402_PAYMENT_REQUIRED,
+                    detail={
+                        "code": "seat_limit_exceeded",
+                        "role": seat_result.role,
+                        "current": seat_result.current,
+                        "limit": seat_result.limit,
+                        "upgrade_url": "/account/billing",
+                    },
+                )
+
     # Check if email already exists
     result = await db.execute(select(User).where(User.email == user_data.email))
     existing_user = result.scalar_one_or_none()

backend/app/api/endpoints/oauth.py

@@ -118,6 +118,29 @@ async def _sign_in_or_register(
 
     if is_new_user:
         if invite_record is not None:
+            # Seat enforcement: re-check at OAuth accept time (race-condition guard).
+            if invite_record.role in ("engineer", "l1_tech"):
+                from app.core.subscriptions import get_account_subscription
+                from app.services.seat_enforcement import check_seat_available
+                sub = await get_account_subscription(invite_record.account_id, db)
+                if sub is not None:
+                    acct_result = await db.execute(
+                        select(Account).where(Account.id == invite_record.account_id)
+                    )
+                    acct = acct_result.scalar_one()
+                    seat_result = await check_seat_available(acct, sub, invite_record.role, db)
+                    if not seat_result.available:
+                        raise HTTPException(
+                            status_code=402,
+                            detail={
+                                "code": "seat_limit_exceeded",
+                                "role": seat_result.role,
+                                "current": seat_result.current,
+                                "limit": seat_result.limit,
+                                "upgrade_url": "/account/billing",
+                            },
+                        )
+
             # Join the invited account directly — no personal account, no
             # trial creation.
             user = User(