perf: up to 5000% faster permissions calculation (#14631)

In large projects, calculating the `permissions` object is one of the
slowest parts of Payload. This PR completely rewrites the permission
calculation system to make it significantly faster and more reliable.

The permissions object is calculated multiple times throughout Payload's
lifecycle: for the entire config every time we load or navigate to any
admin panel page, on every API endpoint call, and as part of query path
validation when calling any Payload operation.
This is done by `getAccessResults` without any document data, and in
large configs can be one of the slowest operations, noticeably slowing
down admin panel navigation.

After this rewrite, **speed improvements in permissions calculation
without data range from 5.3% (access-control test suite) to 74% (fields
test suite - our largest config)**. The larger the config, the more
noticeable these improvements become. These performance gains apply to
both the Payload Admin Panel and API requests.

---

The `permissions` object can also be calculated WITH document data,
which triggers evaluation of `Where` conditions in
collection/global-level access control and may fetch the document to
pass to access control functions.

This has been heavily optimized with **speed improvements for
permissions calculation with data ranging between 75% and 5138%** (if I
craft a collection config that excessively uses aspects this PR
improves) in the benchmarks. This optimization affects:

- Loading any document (collection/global edit view or drawer)
- Saving a document
- Loading the list view with query presets applied
- Bulk upload initialization (runs twice)

These improvements are most noticeable when navigating _to_ documents in
the admin panel.

## What's Fixed

In addition to performance improvements, the new function is now
cleaner, easier to understand and works more reliably. I specifically
wanna call out two issues that were fixed:

**Field access control data bug**: Added a new e2e test that was
previously failing - when saving a document, the data object passed to
field-level update access control functions had the wrong shape (or in
some cases did not exist at all). This caused fields to show incorrect
`readOnly` states after save. The new implementation properly passes
document data through all access control checks.

**Where query validation**: The old implementation sometimes skipped
validating `Where` queries for collections when `req.data` existed,
potentially granting incorrect access. The new version always validates
where queries correctly when `fetchData: true`.

**Global Where queries:**: Where queries were _never_ executed for
globals. Instead, [we were just checking if the global existed in
general](https://github.com/payloadcms/payload/blob/main/packages/payload/src/utilities/getEntityPolicies.ts#L59).
This PR ensures that `Where` queries returned from global access control
are respected.


## What's Faster (and Why)

**Where query caching:** When multiple operations return identical where
queries (common pattern), we now cache the result. Instead of 3-4
separate DB calls, we make 1 call and reuse it.

**Parallel execution:** All `Where` query evaluations and async access
control functions (for both collections and fields) now execute
concurrently with maximum parallelism, rather than sequentially.

**Optimized DB operations**: When evaluating returned `Where` queries,
we now use direct database `db.count()` queries instead of
`payload.find()` operations. This is much faster (especially on
Postgres).

**Synchronous tree traversal**: The entire field permission tree is now
built synchronously with all async work collected and executed in
parallel at the end, rather than cascading await calls through each
nesting level. This eliminates sequential bottlenecks in deeply nested
field structures.

## Benchmarks

### Admin Panel

- Fields test suite with access control added
- 1000 blocks added to the blocks collection. This is not as excessive
as you would expect:
- most Payload apps do not run on an M3 Max. CPU/DB is often much, much
slower
  - this is all local, with a local DB
- a lot of projects accumulate a huge amount of blocks if you multiply
blocks x block fields. They can definitely reach 1000 total blocks
- each block is simple - only one text field per block. In real
projects, blocks are usually a lot more complex

**Before:**


https://github.com/user-attachments/assets/37b55f02-6dbc-4005-9da6-d7cd4bfdc925

**After:**


https://github.com/user-attachments/assets/8dd796dd-66ed-4d32-a688-27b4169577c6

Branch:
https://github.com/payloadcms/payload/tree/fix/update-field-access-control-after-save-benchmarks

### Modified Access-Control Test Suite

`cd test && pnpm payload run access-control/benchmark-permissions.ts`

```md
📊 Benchmark 1: getAccessResults (all collections + globals)
──────────────────────────────────────────────────────────────────────
┌─────────┬───────────────────┬─────────┬───────────────────┬──────────┐
│ (index) │ Task Name         │ ops/sec │ Average Time (ms) │ Margin   │
├─────────┼───────────────────┼─────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (optimized)' │ '16.91' │ '59203.986'       │ '±0.52%' │
│ 1       │ 'OLD (previous)'  │ '16.07' │ '62323.953'       │ '±0.57%' │
└─────────┴───────────────────┴─────────┴───────────────────┴──────────┘
  ⚡ Speedup: +5.3% 🚀
  📊 DB Calls per operation (across all collections + globals):
     NEW: 0.0 total (0.0 data, 0.0 where)
     OLD: 0.0 total (0.0 data, 0.0 where)

📊 Benchmark 2: docAccessOperation (with fetchData)
──────────────────────────────────────────────────────────────────────
  Collection: where-cache-same (same where queries)

┌─────────┬────────────────────┬───────────┬───────────────────┬──────────┐
│ (index) │ Task Name          │ ops/sec   │ Average Time (ms) │ Margin   │
├─────────┼────────────────────┼───────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (with cache)' │ '2272.81' │ '442.319'         │ '±0.11%' │
│ 1       │ 'OLD (no cache)'   │ '1019.72' │ '983.347'         │ '±0.12%' │
└─────────┴────────────────────┴───────────┴───────────────────┴──────────┘
  ⚡ Speedup: +122.9% 🚀
  📊 DB Calls per operation:
     NEW: 2.0 total (1.0 data, 1.0 where)
     OLD: 4.0 total (1.0 data, 3.0 where)

📊 Benchmark 3: docAccessOperation (with data passed)
──────────────────────────────────────────────────────────────────────
  Collection: where-cache-same (same where queries, no DB fetch)

┌─────────┬────────────────────┬───────────┬───────────────────┬──────────┐
│ (index) │ Task Name          │ ops/sec   │ Average Time (ms) │ Margin   │
├─────────┼────────────────────┼───────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (with cache)' │ '4945.43' │ '203.252'         │ '±0.11%' │
│ 1       │ 'OLD (no cache)'   │ '1023.75' │ '979.898'         │ '±0.14%' │
└─────────┴────────────────────┴───────────┴───────────────────┴──────────┘
  ⚡ Speedup: +383.1% 🚀
  📊 DB Calls per operation:
     NEW: 1.0 total (0.0 data, 1.0 where)
     OLD: 4.0 total (1.0 data, 3.0 where)

📊 Benchmark 4: docAccessOperation (unique where queries)
──────────────────────────────────────────────────────────────────────
  Collection: where-cache-unique (unique where queries per operation)

┌─────────┬────────────────────┬───────────┬───────────────────┬──────────┐
│ (index) │ Task Name          │ ops/sec   │ Average Time (ms) │ Margin   │
├─────────┼────────────────────┼───────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (parallel)'   │ '1693.67' │ '599.091'         │ '±0.29%' │
│ 1       │ 'OLD (sequential)' │ '970.37'  │ '1036.268'        │ '±0.20%' │
└─────────┴────────────────────┴───────────┴───────────────────┴──────────┘
  ⚡ Speedup: +74.5% 🚀
  📊 DB Calls per operation:
     NEW: 4.0 total (1.0 data, 3.0 where)
     OLD: 4.0 total (1.0 data, 3.0 where)

📊 Benchmark 5: Complex Collection (async access, nested blocks, field access)
──────────────────────────────────────────────────────────────────────
  Collection: complex-content (stress test)

┌─────────┬────────────────────┬──────────┬───────────────────┬──────────┐
│ (index) │ Task Name          │ ops/sec  │ Average Time (ms) │ Margin   │
├─────────┼────────────────────┼──────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (optimized)'  │ '133.17' │ '7683.346'        │ '±0.83%' │
│ 1       │ 'OLD (sequential)' │ '72.86'  │ '13901.616'       │ '±0.82%' │
└─────────┴────────────────────┴──────────┴───────────────────┴──────────┘
  ⚡ Speedup: +82.8% 🚀
  📊 DB Calls per operation:
     NEW: 2.0 total (1.0 data, 1.0 where)
     OLD: 2.0 total (1.0 data, 1.0 where)

📊 Benchmark 6: Sync-Heavy Collection (same where, many sync field access)
──────────────────────────────────────────────────────────────────────
  Collection: sync-heavy (where cache + field access)

┌─────────┬────────────────────┬───────────┬───────────────────┬──────────┐
│ (index) │ Task Name          │ ops/sec   │ Average Time (ms) │ Margin   │
├─────────┼────────────────────┼───────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (with cache)' │ '3607.72' │ '279.559'         │ '±0.15%' │
│ 1       │ 'OLD (no cache)'   │ '68.87'   │ '15136.557'       │ '±1.44%' │
└─────────┴────────────────────┴───────────┴───────────────────┴──────────┘
  ⚡ Speedup: +5138.5% 🚀
  📊 DB Calls per operation:
     NEW: 1.0 total (0.0 data, 1.0 where)
     OLD: 5.0 total (1.0 data, 4.0 where)

══════════════════════════════════════════════════════════════════════
📈 Summary:
══════════════════════════════════════════════════════════════════════
  1. getAccessResults:                        (see above)
  2. docAccessOperation (with fetchData):     (see above)
  3. docAccessOperation (with data passed):   (see above)
  4. docAccessOperation (unique where):       (see above)
  5. Complex collection (async + nested):     (see above)
  6. Sync-heavy (where cache + fields):       (see above)
══════════════════════════════════════════════════════════════════════
```

### Fields Test Suite

`cd test && pnpm payload run fields/benchmark-getAccessResults.ts`

```md
📊 Benchmark: getAccessResults (all fields test collections + globals)
──────────────────────────────────────────────────────────────────────
┌─────────┬───────────────────┬───────────┬───────────────────┬──────────┐
│ (index) │ Task Name         │ ops/sec   │ Average Time (ms) │ Margin   │
├─────────┼───────────────────┼───────────┼───────────────────┼──────────┤
│ 0       │ 'NEW (optimized)' │ '2104.06' │ '478.382'         │ '±0.18%' │
│ 1       │ 'OLD (previous)'  │ '1208.14' │ '834.974'         │ '±0.21%' │
└─────────┴───────────────────┴───────────┴───────────────────┴──────────┘

  ⚡ Speedup: +74.2% 🚀
  📊 DB Calls per operation (across all collections + globals):
     NEW: 0.0 total (0.0 data, 0.0 where)
     OLD: 0.0 total (0.0 data, 0.0 where)
```

Author: AlessioGr

docs/access-control/overview.mdx

@@ -56,12 +56,14 @@ To accomplish this, Payload exposes the [Access Operation](../authentication/ope
 
 <Banner type="warning">
   **Important:** When your access control functions are executed via the [Access
-  Operation](../authentication/operations#access), the `id` and `data` arguments
-  will be `undefined`. This is because Payload is executing your functions
-  without referencing a specific Document.
+  Operation](../authentication/operations#access), the `id`, `data`, `siblingData`, `blockData` and `doc` arguments
+  will be `undefined`. Additionally, `Where` queries returned from access control functions will not be run - we'll assume the user does not have access instead.
+
+This is because Payload is executing your functions without referencing a specific Document.
+
 </Banner>
 
-If you use `id` or `data` within your access control functions, make sure to check that they are defined first. If they are not, then you can assume that your Access Control is being executed via the Access Operation to determine solely what the user can do within the Admin Panel.
+If you use `id`, `data`, `siblingData`, `blockData` and `doc` within your access control functions, make sure to check that they are defined first. If they are not, then you can assume that your Access Control is being executed via the Access Operation to determine solely what the user can do within the Admin Panel.
 
 ## Locale Specific Access Control
 

packages/next/src/views/Document/getDocumentPermissions.tsx

@@ -16,6 +16,9 @@ export const getDocumentPermissions = async (args: {
   collectionConfig?: SanitizedCollectionConfig
   data: Data
   globalConfig?: SanitizedGlobalConfig
+  /**
+   * When called for creating a new document, id is not provided.
+   */
   id?: number | string
   req: PayloadRequest
 }): Promise<{
@@ -35,29 +38,27 @@ export const getDocumentPermissions = async (args: {
         collection: {
           config: collectionConfig,
         },
-        req: {
-          ...req,
-          data: {
-            ...data,
-            _status: 'draft',
-          },
+        data: {
+          ...data,
+          _status: 'draft',
         },
+        req,
       })
 
       if (collectionConfig.versions?.drafts) {
-        hasPublishPermission = await docAccessOperation({
-          id,
-          collection: {
-            config: collectionConfig,
-          },
-          req: {
-            ...req,
+        hasPublishPermission = (
+          await docAccessOperation({
+            id,
+            collection: {
+              config: collectionConfig,
+            },
             data: {
               ...data,
               _status: 'published',
             },
-          },
-        }).then((permissions) => permissions.update)
+            req,
+          })
+        ).update
       }
     } catch (err) {
       logError({ err, payload: req.payload })
@@ -67,24 +68,22 @@ export const getDocumentPermissions = async (args: {
   if (globalConfig) {
     try {
       docPermissions = await docAccessOperationGlobal({
+        data,
         globalConfig,
-        req: {
-          ...req,
-          data,
-        },
+        req,
       })
 
       if (globalConfig.versions?.drafts) {
-        hasPublishPermission = await docAccessOperationGlobal({
-          globalConfig,
-          req: {
-            ...req,
+        hasPublishPermission = (
+          await docAccessOperationGlobal({
             data: {
               ...data,
               _status: 'published',
             },
-          },
-        }).then((permissions) => permissions.update)
+            globalConfig,
+            req,
+          })
+        ).update
       }
     } catch (err) {
       logError({ err, payload: req.payload })

packages/payload/package.json

@@ -45,6 +45,11 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./internal": {
+      "import": "./src/exports/internal.ts",
+      "types": "./src/exports/internal.ts",
+      "default": "./src/exports/internal.ts"
+    },
     "./shared": {
       "import": "./src/exports/shared.ts",
       "types": "./src/exports/shared.ts",
@@ -150,6 +155,11 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       },
+      "./internal": {
+        "import": "./dist/exports/internal.js",
+        "types": "./dist/exports/internal.d.ts",
+        "default": "./dist/exports/internal.js"
+      },
       "./node": {
         "import": "./dist/exports/node.js",
         "types": "./dist/exports/node.d.ts",

packages/payload/src/auth/getAccessResults.ts

@@ -1,7 +1,7 @@
 import type { AllOperations, PayloadRequest } from '../types/index.js'
 import type { Permissions, SanitizedPermissions } from './types.js'
 
-import { getEntityPolicies } from '../utilities/getEntityPolicies.js'
+import { getEntityPermissions } from '../utilities/getEntityPermissions/getEntityPermissions.js'
 import { sanitizePermissions } from '../utilities/sanitizePermissions.js'
 
 type GetAccessResultsArgs = {
@@ -27,7 +27,7 @@ export async function getAccessResults({
   } else {
     results.canAccessAdmin = false
   }
-  const blockPolicies = {}
+  const blockReferencesPermissions = {}
 
   await Promise.all(
     payload.config.collections.map(async (collection) => {
@@ -45,14 +45,15 @@ export async function getAccessResults({
         collectionOperations.push('readVersions')
       }
 
-      const collectionPolicy = await getEntityPolicies({
-        type: 'collection',
-        blockPolicies,
+      const collectionPermissions = await getEntityPermissions({
+        blockReferencesPermissions,
         entity: collection,
+        entityType: 'collection',
+        fetchData: false,
         operations: collectionOperations,
         req,
       })
-      results.collections![collection.slug] = collectionPolicy
+      results.collections![collection.slug] = collectionPermissions
     }),
   )
 
@@ -64,14 +65,15 @@ export async function getAccessResults({
         globalOperations.push('readVersions')
       }
 
-      const globalPolicy = await getEntityPolicies({
-        type: 'global',
-        blockPolicies,
+      const globalPermissions = await getEntityPermissions({
+        blockReferencesPermissions,
         entity: global,
+        entityType: 'global',
+        fetchData: false,
         operations: globalOperations,
         req,
       })
-      results.globals![global.slug] = globalPolicy
+      results.globals![global.slug] = globalPermissions
     }),
   )
 

packages/payload/src/auth/types.ts

@@ -28,11 +28,9 @@ export type SanitizedBlockPermissions =
     }
   | true
 
-export type BlocksPermissions =
-  | {
-      [blockSlug: string]: BlockPermissions
-    }
-  | true
+export type BlocksPermissions = {
+  [blockSlug: string]: BlockPermissions
+}
 
 export type SanitizedBlocksPermissions =
   | {
@@ -42,10 +40,10 @@ export type SanitizedBlocksPermissions =
 
 export type FieldPermissions = {
   blocks?: BlocksPermissions
-  create: Permission
+  create?: Permission
   fields?: FieldsPermissions
-  read: Permission
-  update: Permission
+  read?: Permission
+  update?: Permission
 }
 
 export type SanitizedFieldPermissions =
@@ -65,12 +63,14 @@ export type SanitizedFieldsPermissions =
   | true
 
 export type CollectionPermission = {
-  create: Permission
-  delete: Permission
+  create?: Permission
+  delete?: Permission
   fields: FieldsPermissions
-  read: Permission
+  read?: Permission
   readVersions?: Permission
-  update: Permission
+  // Auth-enabled Collections only
+  unlock?: Permission
+  update?: Permission
 }
 
 export type SanitizedCollectionPermission = {
@@ -79,14 +79,16 @@ export type SanitizedCollectionPermission = {
   fields: SanitizedFieldsPermissions
   read?: true
   readVersions?: true
+  // Auth-enabled Collections only
+  unlock?: true
   update?: true
 }
 
 export type GlobalPermission = {
   fields: FieldsPermissions
-  read: Permission
+  read?: Permission
   readVersions?: Permission
-  update: Permission
+  update?: Permission
 }
 
 export type SanitizedGlobalPermission = {

packages/payload/src/collections/operations/docAccess.ts

@@ -1,23 +1,31 @@
 import type { SanitizedCollectionPermission } from '../../auth/index.js'
-import type { AllOperations, PayloadRequest } from '../../types/index.js'
+import type { AllOperations, JsonObject, PayloadRequest } from '../../types/index.js'
 import type { Collection } from '../config/types.js'
 
-import { getEntityPolicies } from '../../utilities/getEntityPolicies.js'
+import { getEntityPermissions } from '../../utilities/getEntityPermissions/getEntityPermissions.js'
 import { killTransaction } from '../../utilities/killTransaction.js'
 import { sanitizePermissions } from '../../utilities/sanitizePermissions.js'
 
 const allOperations: AllOperations[] = ['create', 'read', 'update', 'delete']
 
 type Arguments = {
   collection: Collection
-  id: number | string
+  /**
+   * If the document data is passed, it will be used to check access instead of fetching the document from the database.
+   */
+  data?: JsonObject
+  /**
+   * When called for creating a new document, id is not provided.
+   */
+  id?: number | string
   req: PayloadRequest
 }
 
 export async function docAccessOperation(args: Arguments): Promise<SanitizedCollectionPermission> {
   const {
     id,
     collection: { config },
+    data,
     req,
   } = args
 
@@ -36,11 +44,13 @@ export async function docAccessOperation(args: Arguments): Promise<SanitizedColl
   }
 
   try {
-    const result = await getEntityPolicies({
-      id,
-      type: 'collection',
-      blockPolicies: {},
+    const result = await getEntityPermissions({
+      id: id!,
+      blockReferencesPermissions: {},
+      data,
       entity: config,
+      entityType: 'collection',
+      fetchData: id ? true : (false as true),
       operations: collectionOperations,
       req,
     })

packages/payload/src/config/types.ts

@@ -43,6 +43,7 @@ import type { RootFoldersConfiguration } from '../folders/types.js'
 import type { GlobalConfig, Globals, SanitizedGlobalConfig } from '../globals/config/types.js'
 import type {
   Block,
+  DefaultDocumentIDType,
   FlattenedBlock,
   JobsConfig,
   KVAdapterResult,
@@ -314,7 +315,7 @@ export type AccessArgs<TData = any> = {
    */
   data?: TData
   /** ID of the resource being accessed */
-  id?: number | string
+  id?: DefaultDocumentIDType
   /** If true, the request is for a static file */
   isReadingStaticFile?: boolean
   /** The original request that requires an access check */

packages/payload/src/database/queryValidation/types.ts

@@ -1,6 +1,7 @@
 import type { CollectionPermission, GlobalPermission } from '../../auth/index.js'
 import type { FlattenedField } from '../../fields/config/types.js'
 
+// TODO: Rename to EntityPermissions in 4.0
 export type EntityPolicies = {
   collections?: {
     [collectionSlug: string]: CollectionPermission

packages/payload/src/database/queryValidation/validateQueryPaths.ts

@@ -11,6 +11,7 @@ import { validateSearchParam } from './validateSearchParams.js'
 type Args = {
   errors?: { path: string }[]
   overrideAccess: boolean
+  // TODO: Rename to permissions or entityPermissions in 4.0
   policies?: EntityPolicies
   polymorphicJoin?: boolean
   req: PayloadRequest

packages/payload/src/database/queryValidation/validateSearchParams.ts

@@ -5,7 +5,7 @@ import type { PayloadRequest, WhereField } from '../../types/index.js'
 import type { EntityPolicies, PathToQuery } from './types.js'
 
 import { fieldAffectsData } from '../../fields/config/types.js'
-import { getEntityPolicies } from '../../utilities/getEntityPolicies.js'
+import { getEntityPermissions } from '../../utilities/getEntityPermissions/getEntityPermissions.js'
 import { isolateObjectProperty } from '../../utilities/isolateObjectProperty.js'
 import { getLocalizedPaths } from '../getLocalizedPaths.js'
 import { validateQueryPaths } from './validateQueryPaths.js'
@@ -20,6 +20,7 @@ type Args = {
   overrideAccess: boolean
   parentIsLocalized?: boolean
   path: string
+  // TODO: Rename to permissions or entityPermissions in 4.0
   policies: EntityPolicies
   polymorphicJoin?: boolean
   req: PayloadRequest
@@ -56,13 +57,14 @@ export async function validateSearchParam({
   let paths: PathToQuery[] = []
   const { slug } = (collectionConfig || globalConfig)!
 
-  const blockPolicies = {}
+  const blockReferencesPermissions = {}
 
   if (globalConfig && !policies.globals![slug]) {
-    policies.globals![slug] = await getEntityPolicies({
-      type: 'global',
-      blockPolicies,
+    policies.globals![slug] = await getEntityPermissions({
+      blockReferencesPermissions,
       entity: globalConfig,
+      entityType: 'global',
+      fetchData: false,
       operations: ['read'],
       req,
     })
@@ -123,10 +125,11 @@ export async function validateSearchParam({
       if (!overrideAccess && fieldAffectsData(field)) {
         if (collectionSlug) {
           if (!policies.collections![collectionSlug]) {
-            policies.collections![collectionSlug] = await getEntityPolicies({
-              type: 'collection',
-              blockPolicies,
+            policies.collections![collectionSlug] = await getEntityPermissions({
+              blockReferencesPermissions,
               entity: req.payload.collections[collectionSlug]!.config,
+              entityType: 'collection',
+              fetchData: false,
               operations: ['read'],
               req: isolateObjectProperty(req, 'transactionID'),
             })