Clarify cache helper callback flow

Author: premtsd-code

src/Database/Database.php

@@ -8567,9 +8567,10 @@ public function find(string $collection, array $queries = [], string $forPermiss
     /**
      * Execute a callback behind a cache-aside lookup.
      *
-     * The callback value is returned to the caller. Use $toCache when the
-     * returned value needs to be serialized before saving, and $fromCache when
-     * the cached payload needs validation or hydration before reuse.
+     * The callback runs on cache miss and its value is returned to the caller.
+     * Use $toCache when that value needs serialization before saving, and
+     * $fromCache when the cached payload needs validation or hydration before
+     * reuse.
      *
      * @template T
      * @param string $key

tests/unit/ListCacheTest.php

@@ -46,6 +46,36 @@ private function seedProject(Database $database, string $id, string $name): void
         ]));
     }
 
+    public function testWithCacheUsesCallbackOnMissAndCachesResult(): void
+    {
+        $cache = new HashMemoryCache();
+        $database = $this->createDatabase($cache);
+
+        $callbackCalls = 0;
+
+        $value = $database->withCache(
+            'key',
+            function () use (&$callbackCalls): array {
+                $callbackCalls++;
+                return ['value' => 'fresh'];
+            },
+        );
+
+        $this->assertSame(['value' => 'fresh'], $value);
+        $this->assertSame(1, $callbackCalls);
+
+        $value = $database->withCache(
+            'key',
+            function () use (&$callbackCalls): array {
+                $callbackCalls++;
+                return ['value' => 'new'];
+            },
+        );
+
+        $this->assertSame(['value' => 'fresh'], $value);
+        $this->assertSame(1, $callbackCalls);
+    }
+
     public function testWithCacheReturnsValidatedCachedValue(): void
     {
         $cache = new HashMemoryCache();