fix(permission-groups): preserve bulk membership behavior and locked entitlement checks

Author: waleedlatif1

apps/docs/content/docs/cli/permission-groups.mdx

@@ -46,7 +46,7 @@ Bulk Add Permission Group Members (OAuth login or personal API key required)
 | `--organization <value>` | Yes | Organization that owns the permission group. |
 | `--group <value>` | Yes | Permission group identifier. |
 | `--user-ids <json\|@file>` | No | Organization member identifiers. Existing group members are skipped; users outside the organization are ignored. (JSON, or @path / @- to read a file or stdin). |
-| `--add-all-organization-members` | No | Add every current organization member, up to 1000. For larger organizations, use userIds in batches. Cannot be combined with userIds. |
+| `--add-all-organization-members` | No | Add every current organization member in bounded batches within one transaction. Cannot be combined with userIds. |
 | `--no-add-all-organization-members` | No | Send --add-all-organization-members as false. |
 
 </CommandTable>
@@ -254,7 +254,7 @@ Update Permission Group (OAuth login or personal API key required)
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization that owns the permission group. |
 | `--name <value>` | No | Group name, unique within the organization. |
-| `--description <value>` | No | Group description. Null clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
+| `--description <value>` | No | Group description. Null or an empty string clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
 | `--config <json\|@file>` | No | Patch of permission restrictions. Omitted keys remain unchanged; each supplied array replaces that entire list. (JSON, or @path / @- to read a file or stdin). |
 | `--is-default` | No | Whether the group is the organization default. Only one group can be the default. |
 | `--no-is-default` | No | Send --is-default as false. |

apps/docs/content/docs/cli/reference.mdx

@@ -3037,7 +3037,7 @@ sim permission-groups members batch-add [options]
 | `--organization <value>` | Yes | Organization that owns the permission group. |
 | `--group <value>` | Yes | Permission group identifier. |
 | `--user-ids <json\|@file>` | No | Organization member identifiers. Existing group members are skipped; users outside the organization are ignored. (JSON, or @path / @- to read a file or stdin). |
-| `--add-all-organization-members` | No | Add every current organization member, up to 1000. For larger organizations, use userIds in batches. Cannot be combined with userIds. |
+| `--add-all-organization-members` | No | Add every current organization member in bounded batches within one transaction. Cannot be combined with userIds. |
 | `--no-add-all-organization-members` | No | Send --add-all-organization-members as false. |
 
 </CommandTable>
@@ -3245,7 +3245,7 @@ sim permission-groups update <groupId> [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization that owns the permission group. |
 | `--name <value>` | No | Group name, unique within the organization. |
-| `--description <value>` | No | Group description. Null clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
+| `--description <value>` | No | Group description. Null or an empty string clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
 | `--config <json\|@file>` | No | Patch of permission restrictions. Omitted keys remain unchanged; each supplied array replaces that entire list. (JSON, or @path / @- to read a file or stdin). |
 | `--is-default` | No | Whether the group is the organization default. Only one group can be the default. |
 | `--no-is-default` | No | Send --is-default as false. |

apps/docs/lib/openapi-download.test.ts

@@ -33,7 +33,7 @@ describe('OpenAPI download', () => {
     const tags = document.tags as Array<{ name: string }>
 
     expect(document.openapi).toBe('3.1.0')
-    expect(Object.keys(paths)).toHaveLength(157)
+    expect(Object.keys(paths)).toHaveLength(163)
     expect(tags.map((tag) => tag.name)).toEqual([
       'Workspace Sync',
       'Workflows',
@@ -44,6 +44,7 @@ describe('OpenAPI download', () => {
       'Tables',
       'Knowledge Bases',
       'Billing',
+      'Permission Groups',
       'Meta',
       'Workspaces',
       'MCP Servers',

apps/docs/openapi-v2-resources.json

@@ -5524,7 +5524,7 @@
       "post": {
         "operationId": "bulkAddPermissionGroupMembers",
         "summary": "Bulk Add Permission Group Members",
-        "description": "Assign up to 1000 organization members atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.members.bulk_add",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -12628,7 +12628,7 @@
           },
           "isDefault": {
             "type": "boolean",
-            "description": "Whether this is the organization default, which applies across all its workspaces."
+            "description": "Whether this is the organization default, which applies to everyone across all its workspaces regardless of member assignments."
           },
           "membershipMode": {
             "type": "string",
@@ -13266,7 +13266,7 @@
             "description": "Group name, unique within the organization."
           },
           "description": {
-            "description": "Group description. Null clears it; omission leaves it unchanged.",
+            "description": "Group description. Null or an empty string clears it; omission leaves it unchanged.",
             "anyOf": [
               {
                 "type": "string",
@@ -13847,7 +13847,7 @@
             }
           },
           "addAllOrganizationMembers": {
-            "description": "Add every current organization member, up to 1000. For larger organizations, use userIds in batches. Cannot be combined with userIds.",
+            "description": "Add every current organization member in bounded batches within one transaction. Cannot be combined with userIds.",
             "type": "boolean"
           }
         },

apps/sim/app/api/organizations/[id]/permission-groups/[groupId]/route.test.ts

@@ -77,7 +77,9 @@ async function updateUnderLock(body: UpdatePermissionGroupBody) {
   })
   try {
     expect(await Promise.race([lockEntered.promise, pendingResponse.then(() => false)])).toBe(true)
-    expect(mocks.acquireLock).toHaveBeenCalledExactlyOnceWith(db, ORGANIZATION_ID)
+    expect(mocks.acquireLock).toHaveBeenCalledExactlyOnceWith(db, ORGANIZATION_ID, {
+      lockTimeoutAlreadyBounded: true,
+    })
     expect(dbChainMockFns.update).not.toHaveBeenCalled()
   } finally {
     lockReleased.resolve()
@@ -161,7 +163,9 @@ describe('permission group PUT policy serialization', () => {
 
     expect(response.status).toBe(404)
     await expect(response.json()).resolves.toMatchObject({ error: 'Permission group not found' })
-    expect(mocks.acquireLock).toHaveBeenCalledExactlyOnceWith(db, ORGANIZATION_ID)
+    expect(mocks.acquireLock).toHaveBeenCalledExactlyOnceWith(db, ORGANIZATION_ID, {
+      lockTimeoutAlreadyBounded: true,
+    })
     expect(mocks.loadGroup).toHaveBeenLastCalledWith(GROUP_ID, ORGANIZATION_ID, db)
     expect(dbChainMockFns.update).not.toHaveBeenCalled()
   })

apps/sim/lib/api/contracts/permission-groups.ts

@@ -114,10 +114,10 @@ const workspaceIdsSchema = z.array(z.string().min(1)).max(MAX_PERMISSION_GROUP_W
  * with no `workspaceIds` is already the all-workspaces case and needs no
  * assertion here.
  *
- * Everything else is left to the routes: a non-default group targets the
+ * Other scope rules are enforced by the shared manager: a non-default group targets the
  * workspaces in `workspaceIds` (empty is allowed on update — the group then
  * governs nothing, since the resolver inner-joins the workspace link table), and
- * the create route requires at least one workspace up front.
+ * creation requires at least one workspace up front.
  */
 function refineWorkspaceScope(
   body: { workspaceIds?: string[]; isDefault?: boolean },
@@ -177,7 +177,9 @@ export const updatePermissionGroupBodySchema = z
       .max(500, 'description cannot exceed 500 characters')
       .nullable()
       .optional()
-      .describe('Group description. Null clears it; omission leaves it unchanged.'),
+      .describe(
+        'Group description. Null or an empty string clears it; omission leaves it unchanged.'
+      ),
     config: permissionGroupConfigSchema.optional(),
     isDefault: z
       .boolean()

apps/sim/lib/api/contracts/v2/openapi/permission-groups.ts

@@ -61,8 +61,8 @@ export const permissionGroupOpenApiRoutes = [
       params: documentedSchema(
         v2ListPermissionGroupsContract.params,
         'ListPermissionGroupsParams',
-        'Permission group parameters',
-        'Organization and permission-group identifiers.'
+        'Organization parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListPermissionGroupsContract.query,
@@ -94,8 +94,8 @@ export const permissionGroupOpenApiRoutes = [
       params: documentedSchema(
         v2CreatePermissionGroupContract.params,
         'CreatePermissionGroupParams',
-        'Permission group parameters',
-        'Organization and permission-group identifiers.'
+        'Organization parameters',
+        'Organization identifier.'
       ),
       query: v2CreatePermissionGroupContract.query,
       body: documentedSchema(
@@ -324,7 +324,7 @@ export const permissionGroupOpenApiRoutes = [
       applicationOperation: permissionGroupOperations.bulkAddMembers,
       operationId: 'bulkAddPermissionGroupMembers',
       summary: 'Bulk Add Permission Group Members',
-      description: `Assign up to 1000 organization members atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. ${AUTHORITY}`,
+      description: `Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
@@ -374,8 +374,8 @@ export const permissionGroupOpenApiRoutes = [
       params: documentedSchema(
         v2ListPermissionGroupWorkspacesContract.params,
         'ListPermissionGroupWorkspacesParams',
-        'Permission group parameters',
-        'Organization and permission-group identifiers.'
+        'Organization parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListPermissionGroupWorkspacesContract.query,

apps/sim/lib/api/contracts/v2/permission-groups.ts

@@ -50,7 +50,7 @@ export const v2PermissionGroupSchema = z
     isDefault: z
       .boolean()
       .describe(
-        'Whether this is the organization default, which applies across all its workspaces.'
+        'Whether this is the organization default, which applies to everyone across all its workspaces regardless of member assignments.'
       ),
     membershipMode: z
       .string()
@@ -165,7 +165,7 @@ export const v2BulkAddPermissionGroupMembersBodySchema = z
       .boolean()
       .optional()
       .describe(
-        'Add every current organization member, up to 1000. For larger organizations, use userIds in batches. Cannot be combined with userIds.'
+        'Add every current organization member in bounded batches within one transaction. Cannot be combined with userIds.'
       ),
   })
   .strict()

apps/sim/lib/api/mcp/generated/v2-operations.ts

@@ -387,7 +387,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2BulkAddPermissionGroupMembersContract,
     summary: 'Bulk Add Permission Group Members',
     description:
-      'Assign up to 1000 organization members atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(

apps/sim/lib/permission-groups/application/use-cases.ts

@@ -181,7 +181,9 @@ export const bulkAddPermissionGroupMembers = defineAuthorizedPermissionGroupUseC
             description: `Bulk added ${result.added} member(s) to permission group "${result.group.name}"`,
             metadata: {
               permissionGroupId: result.group.id,
+              added: result.added,
               addedUserIds: result.addedUserIds,
+              ...(result.added > result.addedUserIds.length && { addedUserIdsTruncated: true }),
               skipped: result.skipped,
             },
           },