perf(collections): per-instance memo cache for getCollection

Every find/getDocument call hits Database::getCollection, which in
turn does getDocument(METADATA, id). With a no-op cache adapter
that's a SQL round trip per call — the dominant non-PDO cost on
read-heavy workloads.

Add a small per-Database memo of resolved collection metadata,
keyed by database/namespace/tenant/id so multi-tenant and
shared-table setups stay isolated. Cap at 256 entries with a hard
flush on overflow to keep long-lived workers bounded.

Hand callers a clone of the cached Document — createIndex,
updateAttribute, deleteIndex, etc. mutate the returned Document
in place during normal operation, so a shared reference would let
those mutations leak between calls and corrupt subsequent reads.

Invalidation is wired into purgeCachedCollection,
purgeCachedDocumentInternal (METADATA writes), and Database::delete
to keep the memo coherent with every existing schema-mutation path.

On the focus bench complex_query_nested drops a further 17%
(1794 ms vs 2150 ms) and order_cursor 6% (3661 ms vs 3900 ms)
relative to the previous round.

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

Author: abnegate

src/Database/Database.php

@@ -312,6 +312,25 @@ class Database
      */
     protected bool $eventsSilenced = false;
 
+    /**
+     * Per-instance memoisation of getCollection() results. Avoids the
+     * METADATA SELECT that would otherwise repeat for every find/getDocument
+     * call when the user-provided cache is the No-op adapter.
+     *
+     * Keyed by "{database}::{namespace}::{tenant}::{id}" so multi-tenant /
+     * multi-database/multi-namespace contexts cannot leak across each other.
+     * Entries are invalidated by purgeCachedCollection() and by any code path
+     * that reads or writes the METADATA collection itself (createCollection,
+     * createAttribute, createIndex, deleteAttribute, deleteIndex, etc.) so
+     * the cached metadata never goes stale relative to actual schema.
+     *
+     * @var array<string, Document>
+     */
+    protected array $collectionMetadataCache = [];
+
+    /** Soft cap to prevent unbounded growth in long-lived workers. */
+    protected const COLLECTION_METADATA_CACHE_LIMIT = 256;
+
     protected ?NativeDateTime $timestamp = null;
 
     protected ?Relationships $relationshipHook = null;

src/Database/Traits/Collections.php

@@ -274,6 +274,24 @@ public function updateCollection(string $id, array $permissions, bool $documentS
      */
     public function getCollection(string $id): Document
     {
+        // Memoise within this Database instance so repeated find/getDocument
+        // calls don't replay the METADATA SELECT — especially important when
+        // the user has wired in a no-op cache adapter. The cache key includes
+        // the active database, namespace and tenant so multi-tenant or
+        // shared-table setups stay isolated.
+        $cacheKey = $this->adapter->getDatabase() . '::' . $this->adapter->getNamespace()
+            . '::' . ($this->adapter->getTenant() ?? '') . '::' . $id;
+
+        if (isset($this->collectionMetadataCache[$cacheKey])) {
+            // Always hand callers an independent copy: createIndex,
+            // updateAttribute, etc. mutate the returned Document in-place,
+            // and we cannot allow those mutations to leak between calls.
+            $cached = clone $this->collectionMetadataCache[$cacheKey];
+            $this->trigger(Event::CollectionRead, $cached);
+
+            return $cached;
+        }
+
         // Inline silent() to avoid the per-call Closure allocation. The
         // outer event suppression scope is preserved via try/finally so any
         // ambient silent context still wins.
@@ -294,6 +312,15 @@ public function getCollection(string $id): Document
             return new Document();
         }
 
+        if (! $collection->isEmpty()) {
+            if (\count($this->collectionMetadataCache) >= self::COLLECTION_METADATA_CACHE_LIMIT) {
+                $this->collectionMetadataCache = [];
+            }
+            // Cache a clone so future hits return independent copies even
+            // before the first caller is done mutating their handle.
+            $this->collectionMetadataCache[$cacheKey] = clone $collection;
+        }
+
         $this->trigger(Event::CollectionRead, $collection);
 
         return $collection;

src/Database/Traits/Databases.php

@@ -87,6 +87,10 @@ public function delete(?string $database = null): bool
 
         $this->cache->flush();
 
+        // Drop the in-process metadata memo entirely — the entire database
+        // is gone, so nothing in there is still valid.
+        $this->collectionMetadataCache = [];
+
         return $deleted;
     }
 }

src/Database/Traits/Documents.php

@@ -2055,6 +2055,14 @@ public function purgeCachedCollection(string $collectionId): bool
 
         $this->cache->purge($collectionKey);
 
+        // Invalidate any in-process metadata memo — schema changed.
+        $metadataSuffix = '::'.$collectionId;
+        foreach (\array_keys($this->collectionMetadataCache) as $cachedKey) {
+            if (\str_ends_with((string) $cachedKey, $metadataSuffix)) {
+                unset($this->collectionMetadataCache[$cachedKey]);
+            }
+        }
+
         // Drop every cached validator scoped to this collection id, regardless
         // of the namespace/tenant/maxQueryValues prefix that was active when
         // the entry was built.
@@ -2085,6 +2093,18 @@ protected function purgeCachedDocumentInternal(string $collectionId, ?string $id
         $this->cache->purge($collectionKey, $documentKey);
         $this->cache->purge($documentKey);
 
+        // When the underlying document is a collection definition (i.e. it
+        // lives in the METADATA collection), drop the in-process metadata
+        // memo for that collection too — its schema may have shifted.
+        if ($collectionId === self::METADATA) {
+            $metadataSuffix = '::'.$id;
+            foreach (\array_keys($this->collectionMetadataCache) as $cachedKey) {
+                if (\str_ends_with((string) $cachedKey, $metadataSuffix)) {
+                    unset($this->collectionMetadataCache[$cachedKey]);
+                }
+            }
+        }
+
         return true;
     }