feat: implement negative caching

src/cache/src/FailoverStore.php

@@ -8,12 +8,14 @@
 use Hypervel\Context\CoroutineContext;
 use Hypervel\Contracts\Cache\Lock as LockContract;
 use Hypervel\Contracts\Cache\LockProvider;
+use Hypervel\Contracts\Cache\RawReadable;
 use Hypervel\Contracts\Cache\Repository as RepositoryContract;
 use Hypervel\Contracts\Events\Dispatcher;
 use RuntimeException;
 use Throwable;
+use UnitEnum;
 
-class FailoverStore extends TaggableStore implements LockProvider
+class FailoverStore extends TaggableStore implements LockProvider, RawReadable
 {
     /**
      * Context key prefix for the caches which failed on the last action.
@@ -41,10 +43,18 @@ public function __construct(
 
     /**
      * Retrieve an item from the cache by key.
+     *
+     * Store contract method — unwraps sentinels to null, matching the
+     * pre-refactor behavior (inner Repository's get() also unwrapped).
      */
     public function get(string $key): mixed
     {
-        return $this->attemptOnAllStores(__FUNCTION__, func_get_args());
+        return NullSentinel::unwrap($this->getRaw($key));
+    }
+
+    public function getRaw(UnitEnum|string $key): mixed
+    {
+        return $this->attemptOnAllStores('getRaw', [$key]);
     }
 
     /**
@@ -54,7 +64,15 @@ public function get(string $key): mixed
      */
     public function many(array $keys): array
     {
-        return $this->attemptOnAllStores(__FUNCTION__, func_get_args());
+        return array_map(
+            NullSentinel::unwrap(...),
+            $this->manyRaw(array_map(fn ($k) => (string) $k, $keys))
+        );
+    }
+
+    public function manyRaw(array $keys): array
+    {
+        return $this->attemptOnAllStores('manyRaw', [$keys]);
     }
 
     /**

src/cache/src/MemoizedStore.php

@@ -7,9 +7,13 @@
 use BadMethodCallException;
 use Hypervel\Contracts\Cache\Lock as LockContract;
 use Hypervel\Contracts\Cache\LockProvider;
+use Hypervel\Contracts\Cache\RawReadable;
 use Hypervel\Contracts\Cache\Store;
+use UnitEnum;
 
-class MemoizedStore implements LockProvider, Store
+use function Hypervel\Support\enum_value;
+
+class MemoizedStore implements LockProvider, RawReadable, Store
 {
     /**
      * The memoized cache values.
@@ -29,16 +33,27 @@ public function __construct(
 
     /**
      * Retrieve an item from the cache by key.
+     *
+     * Store contract method — returns the value with sentinels unwrapped to null,
+     * matching the pre-refactor behavior (which returned whatever the inner
+     * Repository's get() returned, i.e., unwrapped). Memoizes the raw value so
+     * subsequent getRaw() calls see the sentinel.
      */
     public function get(string $key): mixed
     {
-        $prefixedKey = $this->prefix($key);
+        return NullSentinel::unwrap($this->getRaw($key));
+    }
+
+    public function getRaw(UnitEnum|string $key): mixed
+    {
+        $stringKey = (string) (is_object($key) ? enum_value($key) : $key);
+        $prefixedKey = $this->prefix($stringKey);
 
         if (array_key_exists($prefixedKey, $this->cache)) {
             return $this->cache[$prefixedKey];
         }
 
-        return $this->cache[$prefixedKey] = $this->repository->get($key);
+        return $this->cache[$prefixedKey] = $this->repository->getRaw($stringKey);
     }
 
     /**
@@ -48,35 +63,39 @@ public function get(string $key): mixed
      */
     public function many(array $keys): array
     {
-        [$memoized, $retrieved, $missing] = [[], [], []];
+        return array_map(
+            NullSentinel::unwrap(...),
+            $this->manyRaw(array_map(fn ($k) => (string) $k, $keys))
+        );
+    }
+
+    public function manyRaw(array $keys): array
+    {
+        [$memoized, $missing] = [[], []];
 
         foreach ($keys as $key) {
             $stringKey = (string) $key;
             $prefixedKey = $this->prefix($stringKey);
 
             if (array_key_exists($prefixedKey, $this->cache)) {
-                $memoized[$key] = $this->cache[$prefixedKey];
+                $memoized[$stringKey] = $this->cache[$prefixedKey];
             } else {
                 $missing[] = $stringKey;
             }
         }
 
+        $retrieved = [];
         if (count($missing) > 0) {
-            $retrieved = tap($this->repository->many($missing), function ($values) {
-                foreach ($values as $key => $value) {
-                    $this->cache[$this->prefix((string) $key)] = $value;
-                }
-            });
+            $retrieved = $this->repository->manyRaw($missing);
+            foreach ($retrieved as $key => $value) {
+                $this->cache[$this->prefix((string) $key)] = $value;
+            }
         }
 
         $result = [];
-
         foreach ($keys as $key) {
-            if (array_key_exists($key, $memoized)) {
-                $result[$key] = $memoized[$key];
-            } else {
-                $result[$key] = $retrieved[$key];
-            }
+            $stringKey = (string) $key;
+            $result[$stringKey] = $memoized[$stringKey] ?? $retrieved[$stringKey] ?? null;
         }
 
         return $result;

src/cache/src/NullSentinel.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Cache;
+
+/**
+ * Namespace for the sentinel array value stored in place of null by the
+ * nullable cache wrapper methods.
+ *
+ * Used by Repository::rememberNullable(), rememberForeverNullable(),
+ * searNullable(), and flexibleNullable() to distinguish "key absent" from
+ * "key present with null value" — the cache contract itself can't express
+ * that distinction via get() alone.
+ *
+ * The sentinel is an array constant, not an object. This is deliberate:
+ * PHP's unserialize() allowed_classes option (used by stores when the
+ * cache.serializable_classes config is set) only restricts object
+ * deserialization. Scalars and arrays round-trip unchanged regardless of
+ * the allowed_classes value. An object sentinel would silently become
+ * __PHP_Incomplete_Class on any cache configured with a restrictive
+ * serializable_classes list that didn't include the sentinel class.
+ *
+ * Identity is checked with strict === against NullSentinel::VALUE, which
+ * is safe because PHP's array equality compares keys and values recursively.
+ * Collision risk is effectively zero: a caller would have to independently
+ * cache a value whose structure is exactly
+ * ['__hypervel_cache_null_sentinel' => true].
+ */
+final class NullSentinel
+{
+    /**
+     * Sentinel value stored in place of null by the nullable cache methods.
+     */
+    public const VALUE = ['__hypervel_cache_null_sentinel' => true];
+
+    /**
+     * Unwrap a value read from the cache — sentinel becomes null; anything else passes through.
+     *
+     * Used at the boundaries where the cache layer returns to public API callers,
+     * so the sentinel never leaks through get/many/remember/flexible/etc.
+     */
+    public static function unwrap(mixed $value): mixed
+    {
+        return $value === self::VALUE ? null : $value;
+    }
+}

src/cache/src/Redis/AllTaggedCache.php

@@ -12,6 +12,7 @@
 use Hypervel\Cache\Events\CacheHit;
 use Hypervel\Cache\Events\CacheMissed;
 use Hypervel\Cache\Events\KeyWritten;
+use Hypervel\Cache\NullSentinel;
 use Hypervel\Cache\RedisStore;
 use Hypervel\Cache\TaggedCache;
 use Hypervel\Contracts\Cache\Store;
@@ -66,7 +67,7 @@ public function add(UnitEnum|string $key, mixed $value, DateInterval|DateTimeInt
             );
 
             if ($result) {
-                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value));
+                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value)));
             }
 
             return $result;
@@ -104,7 +105,7 @@ public function put(array|UnitEnum|string $key, mixed $value, DateInterval|DateT
         );
 
         if ($result) {
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value, $seconds));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value), $seconds));
         }
 
         return $result;
@@ -134,7 +135,7 @@ public function putMany(array $values, DateInterval|DateTimeInterface|int|null $
 
         if ($result) {
             foreach ($values as $key => $value) {
-                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, (string) $key, $value, $seconds));
+                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, (string) $key, NullSentinel::unwrap($value), $seconds));
             }
         }
 
@@ -179,7 +180,7 @@ public function forever(UnitEnum|string $key, mixed $value): bool
         );
 
         if ($result) {
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value)));
         }
 
         return $result;
@@ -242,13 +243,13 @@ public function remember(UnitEnum|string $key, DateInterval|DateTimeInterface|in
         );
 
         if ($wasHit) {
-            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, $value));
+            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, NullSentinel::unwrap($value)));
         } else {
             $this->event(CacheMissed::class, fn (): CacheMissed => new CacheMissed(null, $key));
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value, $seconds));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value), $seconds));
         }
 
-        return $value;
+        return NullSentinel::unwrap($value);
     }
 
     /**
@@ -271,13 +272,13 @@ public function rememberForever(UnitEnum|string $key, Closure $callback): mixed
         );
 
         if ($wasHit) {
-            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, $value));
+            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, NullSentinel::unwrap($value)));
         } else {
             $this->event(CacheMissed::class, fn (): CacheMissed => new CacheMissed(null, $key));
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value)));
         }
 
-        return $value;
+        return NullSentinel::unwrap($value);
     }
 
     /**

src/cache/src/Redis/AnyTaggedCache.php

@@ -14,6 +14,7 @@
 use Hypervel\Cache\Events\CacheHit;
 use Hypervel\Cache\Events\CacheMissed;
 use Hypervel\Cache\Events\KeyWritten;
+use Hypervel\Cache\NullSentinel;
 use Hypervel\Cache\RedisStore;
 use Hypervel\Cache\TaggedCache;
 use Hypervel\Contracts\Cache\Store;
@@ -69,6 +70,17 @@ public function get(array|UnitEnum|string $key, mixed $default = null): mixed
         );
     }
 
+    /**
+     * @throws BadMethodCallException Always - tags are for writing/flushing only
+     */
+    public function getRaw(UnitEnum|string $key): mixed
+    {
+        throw new BadMethodCallException(
+            'Cannot get items via tags in any mode. Tags are for writing and flushing only. '
+            . 'Use Cache::get() directly with the full key.'
+        );
+    }
+
     /**
      * Retrieve multiple items from the cache by key.
      *
@@ -82,6 +94,17 @@ public function many(array $keys): array
         );
     }
 
+    /**
+     * @throws BadMethodCallException Always - tags are for writing/flushing only
+     */
+    public function manyRaw(array $keys): array
+    {
+        throw new BadMethodCallException(
+            'Cannot get items via tags in any mode. Tags are for writing and flushing only. '
+            . 'Use Cache::get() directly.'
+        );
+    }
+
     /**
      * Determine if an item exists in the cache.
      *
@@ -146,7 +169,7 @@ public function put(array|UnitEnum|string $key, mixed $value, DateInterval|DateT
         $result = $this->store->anyTagOps()->put()->execute($key, $value, $seconds, $this->tags->getNames());
 
         if ($result) {
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value, $seconds));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value), $seconds));
         }
 
         return $result;
@@ -171,7 +194,7 @@ public function putMany(array $values, DateInterval|DateTimeInterface|int|null $
 
         if ($result) {
             foreach ($values as $key => $value) {
-                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, (string) $key, $value, $seconds));
+                $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, (string) $key, NullSentinel::unwrap($value), $seconds));
             }
         }
 
@@ -209,7 +232,7 @@ public function forever(UnitEnum|string $key, mixed $value): bool
         $result = $this->store->anyTagOps()->forever()->execute($key, $value, $this->tags->getNames());
 
         if ($result) {
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value)));
         }
 
         return $result;
@@ -289,13 +312,13 @@ public function remember(UnitEnum|string $key, DateInterval|DateTimeInterface|in
         );
 
         if ($wasHit) {
-            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, $value));
+            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, NullSentinel::unwrap($value)));
         } else {
             $this->event(CacheMissed::class, fn (): CacheMissed => new CacheMissed(null, $key));
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value, $seconds));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value), $seconds));
         }
 
-        return $value;
+        return NullSentinel::unwrap($value);
     }
 
     /**
@@ -318,13 +341,13 @@ public function rememberForever(UnitEnum|string $key, Closure $callback): mixed
         );
 
         if ($wasHit) {
-            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, $value));
+            $this->event(CacheHit::class, fn (): CacheHit => new CacheHit(null, $key, NullSentinel::unwrap($value)));
         } else {
             $this->event(CacheMissed::class, fn (): CacheMissed => new CacheMissed(null, $key));
-            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, $value));
+            $this->event(KeyWritten::class, fn (): KeyWritten => new KeyWritten(null, $key, NullSentinel::unwrap($value)));
         }
 
-        return $value;
+        return NullSentinel::unwrap($value);
     }
 
     /**