throw critical exeption when invalidation failed

Author: kai-init

README.md

@@ -61,7 +61,7 @@ At the core of NormCache is **normalized row storage**. Unlike traditional query
 - **Single Storage for Model Rows**: Individual database rows are stored once under canonical primary key IDs (`table:r:<id>`).
 - **Lightweight Query Memberships**: Queries cache only a list of primary key IDs (`table:m:<query_hash>`), not full duplicate model attributes.
 - **$O(1)$ Invalidation Without Redis SCAN**: When a model is updated or deleted, NormCache invalidates only that specific row key (`table:r:<id>`) and advances the table version counter (`table:v`). There are no expensive `KEYS` or `SCAN` commands in Redis.
-- **Global Row Freshness**: Every query reading Post #42 automatically receives the updated row data on its next fetch, ensuring instant consistency across all application queries without clearing individual query keys.
+- **Global Row Freshness**: While Redis is available for invalidation, every query reading Post #42 receives updated row data on its next fetch without clearing individual query keys.
 
 ## Automatic Result & Projection Overlay
 
@@ -126,6 +126,16 @@ php artisan normcache:flush
 
 `flushAll()` and the command advance a global epoch. Old payloads expire naturally; NormCache does not scan Redis keys.
 
+## Redis invalidation outages
+
+NormCache fails open when Redis is unavailable: the database write succeeds and the affected request bypasses cache access. If only that writer cannot reach Redis while other application nodes can still read it, those nodes can serve stale cached data until the affected entry expires or invalidation later succeeds. NormCache logs this condition at `critical` level with the affected table and invalidation mode.
+
+After Redis connectivity is restored, run the global flush to advance the epoch and make any payloads from the outage unreachable:
+
+```bash
+php artisan normcache:flush
+```
+
 ## Temporarily disabling the cache
 
 Use the runtime commands when NormCache needs to be paused across all application nodes without changing configuration or redeploying:

src/Invalidator.php

@@ -13,6 +13,7 @@
 use NormCache\Values\CacheConfig;
 use NormCache\Values\PrimaryKeyMetadata;
 use NormCache\Values\TableIdentity;
+use Psr\Log\LoggerInterface;
 
 final class Invalidator
 {
@@ -28,6 +29,7 @@ public function __construct(
         private readonly PrimaryKeyResolver $primaryKeys,
         private readonly MutationKeyExtractor $mutationKeys,
         private readonly Reporter $reporter,
+        private readonly LoggerInterface $logger,
     ) {}
 
     /** @param array<string, mixed>|null $assigned */
@@ -130,9 +132,9 @@ private function pullInvalidations(string $connection): array
     /** @param list<string> $tokens */
     private function apply(TableIdentity $table, bool $broad, array $tokens): bool
     {
-        try {
-            $mode = $broad ? 'generation' : ($tokens === [] ? 'version' : 'precise');
+        $mode = $broad ? 'generation' : ($tokens === [] ? 'version' : 'precise');
 
+        try {
             $this->store->invalidateTableState(
                 versionKey: $this->keys->version($table),
                 generationKey: $this->keys->generation($table),
@@ -144,6 +146,15 @@ private function apply(TableIdentity $table, bool $broad, array $tokens): bool
 
             return true;
         } catch (\Throwable $exception) {
+            $this->logger->critical(
+                'NormCache invalidation failed; cached reads may be stale.',
+                [
+                    'exception' => $exception,
+                    'table' => $table->connection . ':' . $table->qualifiedTable(),
+                    'mode' => $mode,
+                    'tokens' => $tokens,
+                ],
+            );
             $this->runtime->fail($exception);
 
             return false;

tests/Integration/CacheUnavailableTest.php

@@ -9,6 +9,7 @@
 use NormCache\Support\RedisStore;
 use NormCache\Tests\TestCase;
 use NormCache\Values\CacheConfig;
+use Psr\Log\LoggerInterface;
 
 final class CacheUnavailableTest extends TestCase
 {
@@ -110,6 +111,34 @@ public function test_first_write_fails_open_when_redis_is_not_configured(): void
         );
     }
 
+    public function test_failed_invalidation_is_logged_as_critical(): void
+    {
+        $authorId = DB::table('authors')->insertGetId(['name' => 'Author']);
+        DB::table('posts')->insert([
+            'title' => 'Before',
+            'author_id' => $authorId,
+        ]);
+
+        $store = $this->app->make(RedisStore::class);
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects($this->once())
+            ->method('critical');
+
+        try {
+            $this->app->instance(LoggerInterface::class, $logger);
+            $this->app->instance(
+                RedisStore::class,
+                new RedisStore('missing-normcache-connection'),
+            );
+            $this->app->forgetScopedInstances();
+
+            DB::table('posts')->where('id', 1)->update(['title' => 'After']);
+        } finally {
+            $this->app->instance(RedisStore::class, $store);
+            $this->app->forgetScopedInstances();
+        }
+    }
+
     public function test_disabled_cache_reads_do_not_suppress_write_invalidation(): void
     {
         DB::table('authors')->insert(['id' => 1, 'name' => 'Author']);