docs: update performance docs for prefetch and final numbers

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

Author: jensens

docs/.vale/styles/config/vocabularies/Project/accept.txt

@@ -25,6 +25,7 @@ ZEO
 FileStorage
 ZCatalog
 BTree[s]?
+OOBTree[s]?
 PGJsonb
 GenericSetup
 VectorChord
@@ -243,4 +244,5 @@ pending
 [Aa]uto(detect(ed|s|ion)?|discover(ed|s|y)|creat(ed|es)|inject|appli(ed|es)|populat(ed|es))
 datetime
 [Pp]refetch(ed|er|es|ing)?
+[Pp]luggable
 roundtrips

docs/sources/explanation/performance.md

@@ -314,6 +314,53 @@ N individual queries to 1 batch query. Window-based: only prefetches
 the next batch, not the entire result set (safe for large result sets
 where only a page is rendered).
 
+#### Pluggable refs prefetch (zodb-pgjsonb v1.9.2)
+
+In addition to the explicit `load_multiple()` batch on `getObject()`, the
+storage layer itself can prefetch an object's direct references (annotations,
+sub-mappings, OOBTrees) automatically on every `load()` call. This is
+controlled by a SQL expression registered via
+`storage.register_prefetch_refs_expr()`.
+
+plone-pgcatalog registers the expression at startup:
+
+```python
+storage.register_prefetch_refs_expr(
+    "CASE WHEN idx IS NOT NULL THEN refs END"
+)
+```
+
+This `CASE WHEN idx IS NOT NULL THEN refs END` expression is the result of
+a three-version saga:
+
+- **v1.9.0** prefetched unconditionally for all objects. This caused severe
+  over-fetching: internal ZODB structures (BTrees, PersistentMappings) have
+  refs that cascade into thousands of objects that are never accessed by user
+  code. Cold-start performance was 40--84% *slower* than without prefetch.
+- **v1.9.1** added a class-module blacklist to skip known non-content classes.
+  This was fragile -- any addon adding new persistent classes could reintroduce
+  over-fetching.
+- **v1.9.2** replaced the blacklist with the pluggable SQL expression. The
+  `idx IS NOT NULL` filter is a reliable proxy for "is a content object" because
+  only cataloged content objects have a non-NULL `idx` column in `object_state`.
+  Non-content objects (BTrees, PersistentMappings, Length objects, etc.) never
+  have catalog index data and produce NULL, suppressing the prefetch entirely.
+
+#### Cold vs warm performance summary
+
+With the final `idx IS NOT NULL` filter, the combined batch loading and refs
+prefetch achieves the intended benefit without the over-fetching penalty:
+
+- **Cold start** (empty ZODB cache): page loads with 10--50 `getObject()` calls
+  issue 1--2 batch queries instead of 10--50 individual queries. The refs
+  prefetch warms annotations and workflow state objects ahead of access.
+- **Warm cache** (ZODB cache populated): prefetch calls hit the storage LRU
+  cache and return immediately with no database roundtrips. The overhead of
+  checking the cache is negligible (microseconds).
+- **Large result sets**: window-based batching ensures only the currently
+  rendered page is prefetched. A search returning 10,000 results but rendering
+  25 per page prefetches at most 100 objects (one batch window).
+
 ### ZODB cache sizing
 
 The ZODB Connection cache is the primary performance lever for warm-cache

docs/sources/reference/configuration.md

@@ -61,7 +61,7 @@ need a separate `%import` directive.
 | `PGCATALOG_SLOW_QUERY_MS` | `10` | Threshold in milliseconds for slow query detection. Queries exceeding this are logged as warnings and recorded in the `pgcatalog_slow_queries` table for analysis via the ZMI Slow Queries tab. Set to `0` to disable. |
 | `PGCATALOG_QUERY_CACHE_SIZE` | `200` | Max cached query results per process. Set to `0` to disable. Invalidated when `MAX(tid)` changes (any ZODB commit). Cost-based eviction keeps expensive queries in cache. |
 | `PGCATALOG_QUERY_CACHE_TTR` | `60` | Time-to-round in seconds for datetime values in cache keys. Controls cache key granularity for effectiveRange queries. Higher values = more cache hits but slightly stale effectiveRange. |
-| `PGCATALOG_PREFETCH_BATCH` | `100` | Number of objects to prefetch when `brain.getObject()` is called. Set to `0` to disable. Requires zodb-pgjsonb >= 1.8.0. |
+| `PGCATALOG_PREFETCH_BATCH` | `100` | Number of objects to prefetch when `brain.getObject()` is called. Set to `0` to disable. Requires zodb-pgjsonb >= 1.8.0. In addition, automatic refs prefetch on `load()` is registered at startup when zodb-pgjsonb >= 1.9.2 is available (uses `idx IS NOT NULL` filter to limit prefetch to cataloged content). |
 | `ZODB_TEST_DSN` | `dbname=zodb_test host=localhost port=5433 user=zodb password=zodb` | DSN for test database (tests only). |
 | `BM25_TEST_DSN` | `dbname=zodb_test host=localhost port=5434 user=zodb password=zodb` | DSN for BM25 integration tests (tests only). |
 
@@ -109,7 +109,7 @@ The following registrations are made:
 | `psycopg[binary,pool]>=3.1` | PostgreSQL adapter with connection pooling. |
 | `orjson>=3.9` | Fast JSONB deserialization. |
 | `Products.CMFPlone` | Plone framework. |
-| `zodb-pgjsonb>=1.1` | ZODB storage backend (provides the `object_state` table). |
+| `zodb-pgjsonb>=1.8` | ZODB storage backend (provides the `object_state` table). v1.8.0 adds `load_multiple()` for batch prefetch; v1.9.2 adds `register_prefetch_refs_expr()` for automatic refs prefetch on `load()`. |
 
 ## Optional dependencies