Fix sqlite correctness gap

Author: kai-init

CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Query Builder caching:** supported `DB::table()` reads now participate in NormCache automatically, alongside Eloquent reads. Writes through those cache-aware builders invalidate affected tables automatically.
 - **Unified dependencies:** `dependsOn()` now accepts Eloquent model classes and raw table names in one declaration.
-- **Automatic Result Overlays:** canonical queries returning up to `auto_overlay_max_rows` (default 50) automatically store a complete result payload in Redis, letting warm reads execute in a single Redis `GET` (~80–120 µs) while retaining canonical fallback and self-healing.
+- **Automatic Result Overlays:** canonical queries returning up to `auto_overlay_max_rows + 1` rows automatically store a complete result payload in Redis when its encoded size is at most 50 KiB. The extra row accommodates Laravel's simple/cursor pagination lookahead; with the default value of 50, payloads containing up to 51 rows are eligible. No explicit SQL `LIMIT` is required.
 - **Global tags:** use `tag('name')` to group cached query payloads and `NormCache::flushTag('name')` to invalidate that group.
 - **Unified manual invalidation:** `NormCache::invalidate()` accepts a model instance, model class, table name, or an array of those targets. A model target uses its model connection; table targets use Laravel's default connection unless `connection:` is supplied.
 - **Runtime cache switch:** `normcache:disable` and `normcache:enable`, plus `disableCache()`, `enableCache()`, and `cacheDisabled()`, pause caching across application nodes. Re-enabling advances the global epoch before serving cached data again.

README.md

@@ -67,7 +67,8 @@ At the core of NormCache is **normalized row storage**. Unlike traditional query
 
 NormCache automatically optimizes warm query performance by storing single-step result overlays in Redis for eligible canonical queries:
 
-- **Automatic Promotion**: Canonical queries returning up to `auto_overlay_max_rows` (default `50`) automatically store a serialized result payload in Redis (`table:e:v1:...`).
+- **Automatic Promotion**: Canonical queries returning up to `auto_overlay_max_rows + 1` rows automatically store a serialized result payload in Redis (`table:e:v1:...`) when its encoded size is less than 50 KiB. With the default configuration of `50`, payloads containing up to 51 rows are eligible. An explicit SQL `LIMIT` is not required.
+- **Pagination lookahead allowance**: Laravel's `simplePaginate()` and `cursorPaginate()` fetch one extra row to detect a next page. The one-row allowance avoids excluding a 50-item page solely because its SQL result contains 51 rows. The complete payload, including the lookahead row, must still fit within 50 KiB.
 - **Instant Synchronization & Self-Healing**: Updates to underlying models or dependency tables instantly invalidate the overlay alongside canonical storage. If an overlay key expires or misses, NormCache seamlessly falls back to canonical row assembly and repromotes automatically.
 
 ## Tags and selective flushing
@@ -102,7 +103,7 @@ Author::query()
     ->get();
 ```
 
-`dependsOn()` accepts Eloquent model classes and table names. It authorizes an otherwise opaque query only when NormCache can resolve all declared dependencies. Volatile expressions such as random, UUID, clock, connection-state, or sleep functions are never cached.
+`dependsOn()` accepts Eloquent model classes and table names. It authorizes an otherwise opaque query only when NormCache can resolve all declared dependencies. Recognized volatile expressions—including random, UUID, clock, connection-state, sequence-state, and sleep functions—are never cached.
 
 ## Invalidation
 
@@ -148,6 +149,7 @@ return [
 
     'row_ttl' => 604800,
     'query_ttl' => 3600,
+    // Set to 0 to disable automatic result overlays. Admission allows this value plus one row for pagination lookahead; encoded overlays are capped at 50 KiB.
     'auto_overlay_max_rows' => 50,
 
     'max_precise_invalidation_keys' => 1000,

config/normcache.php

@@ -7,6 +7,8 @@
 
     'row_ttl' => (int) env('NORMCACHE_ROW_TTL', 604800),
     'query_ttl' => (int) env('NORMCACHE_QUERY_TTL', 3600),
+
+    // Set to 0 to disable automatic result overlays. Admission allows one extra row for pagination lookahead; encoded overlays are capped at 50 KiB.
     'auto_overlay_max_rows' => (int) env('NORMCACHE_AUTO_OVERLAY_MAX_ROWS', 50),
 
     // Each group requires connection, database, and table metadata. Add schema to

src/Cache/Engine.php

@@ -26,6 +26,8 @@
 
 final readonly class Engine
 {
+    private const MAX_AUTO_OVERLAY_BYTES = 50 * 1024;
+
     public function __construct(
         private CacheConfig $config,
         private CacheRuntime $runtime,
@@ -395,7 +397,7 @@ private function read(
         ?string $canonicalQueryHash = null,
     ): CacheRead {
         if ($plan->route === QueryPlan::CANONICAL) {
-            return $plan->materializeResult
+            return $plan->materializeResult && $this->config->maxAutoOverlayRows > 0
                 ? $this->readCanonicalWithResultOverlay(
                     $query,
                     $plan,
@@ -1187,7 +1189,10 @@ private function promoteResultPayload(
         bool $wakeWaiters = true,
     ): bool {
         try {
-            if (count($rows) > $this->config->maxAutoOverlayRows) {
+            if (
+                $this->config->maxAutoOverlayRows === 0
+                || count($rows) > $this->config->maxAutoOverlayRows + 1
+            ) {
                 return false;
             }
 
@@ -1199,6 +1204,10 @@ private function promoteResultPayload(
                 $sourceState->tag,
             );
 
+            if (strlen($encoded) > self::MAX_AUTO_OVERLAY_BYTES) {
+                return false;
+            }
+
             $resultState = new CacheState(
                 key: $this->keys->result(
                     $resultPlan->root,

src/Planning/DependencyAnalyzer.php

@@ -283,11 +283,11 @@ private function hasVolatileSqlValue(array $values): bool
     private function isVolatileSql(string $sql): bool
     {
         return preg_match(
-            '/\b(?:rand|random|randomblob|uuid|uuid_short|newid|newsequentialid|gen_random_uuid|uuid_generate_v[0-9]+|nextval|currval|lastval|last_insert_id|last_insert_rowid|changes|total_changes|row_count|found_rows|connection_id|pg_backend_pid|now|sysdate|getdate|sysdatetime|sysutcdatetime|utc_timestamp|utc_date|utc_time|curdate|curtime|clock_timestamp|statement_timestamp|transaction_timestamp|timeofday|sleep|pg_sleep|benchmark)\s*\(/i',
+            '/\b(?:rand|random|randomblob|random_bytes|uuid|uuid_short|newid|newsequentialid|gen_random_uuid|gen_random_bytes|crypt_gen_random|uuid_generate_v[0-9]+|nextval|currval|lastval|setval|last_insert_id|last_insert_rowid|changes|total_changes|row_count|found_rows|connection_id|pg_backend_pid|txid_current|pg_current_xact_id|user|database|schema|current_schema|current_database|current_catalog|current_setting|inet_client_addr|inet_client_port|inet_server_addr|inet_server_port|suser_sname|original_login|host_name|app_name|session_context|context_info|current_request_id|now|sysdate|getdate|sysdatetime|sysutcdatetime|utc_timestamp|utc_date|utc_time|curdate|curtime|clock_timestamp|statement_timestamp|transaction_timestamp|timeofday|sleep|pg_sleep|pg_sleep_for|pg_sleep_until|benchmark)\s*\(/i',
             $sql,
         ) === 1
             || preg_match(
-                '/\b(?:current_timestamp|current_date|current_time|localtimestamp|localtime|current_user|session_user|system_user)\b/i',
+                '/\b(?:current_timestamp|current_date|current_time|localtimestamp|localtime|current_user|session_user|system_user|current_role|current_schema|current_database|current_catalog|current_path)\b/i',
                 $sql,
             ) === 1
             || preg_match(

src/Planning/QueryPlanner.php

@@ -91,7 +91,7 @@ public function plan(
                 $root,
                 $dependencies,
                 $primaryKey,
-                materializeResult: $query->limit !== null,
+                materializeResult: true,
             );
         }
 

src/Planning/TableIdentityResolver.php

@@ -96,7 +96,14 @@ private function doResolve(Connection $connection, string $from): ?TableIdentity
             return null;
         }
 
-        $isView = $this->isView($connection, $schema, $table);
+        $resolvedTable = $this->unqualifiedTable($table);
+
+        if ($driver === 'sqlite') {
+            $schema = strtolower($schema === '' ? 'main' : $schema);
+            $resolvedTable = strtolower($resolvedTable);
+        }
+
+        $isView = $this->isView($connection, $schema, $resolvedTable);
 
         if ($isView === null) {
             return null;
@@ -108,7 +115,7 @@ private function doResolve(Connection $connection, string $from): ?TableIdentity
             database: $database,
             schema: $schema,
             prefix: (string) $connection->getTablePrefix(),
-            table: $this->unqualifiedTable($table),
+            table: $resolvedTable,
             isView: $isView,
         );
     }

src/Values/CacheConfig.php

@@ -33,7 +33,7 @@ public static function fromArray(array $values): self
 
         $rowTtl = self::positive($values, 'row_ttl', 604_800);
         $queryTtl = self::positive($values, 'query_ttl', 3_600);
-        $maxAutoOverlayRows = self::positive(
+        $maxAutoOverlayRows = self::nonNegative(
             $values,
             'auto_overlay_max_rows',
             50,
@@ -76,6 +76,18 @@ private static function positive(array $values, string $key, int $default): int
         return $value;
     }
 
+    /** @param array<string, mixed> $values */
+    private static function nonNegative(array $values, string $key, int $default): int
+    {
+        $value = (int) ($values[$key] ?? $default);
+
+        if ($value < 0) {
+            throw new \InvalidArgumentException("NormCache {$key} must be at least 0.");
+        }
+
+        return $value;
+    }
+
     /** @param array<string, mixed> $values */
     private static function bounded(array $values, string $key, int $maximum): int
     {

src/Values/TableIdentity.php

@@ -56,6 +56,9 @@ public function qualifiedTable(): string
             'mysql', 'mariadb' => $this->database . '.' . $this->table,
             'pgsql' => $this->schema . '.' . $this->table,
             'sqlsrv' => $this->database . '.' . $this->schema . '.' . $this->table,
+            'sqlite' => $this->schema === ''
+                ? $this->table
+                : $this->schema . '.' . $this->table,
             default => $this->table,
         };
     }

tests/Integration/CanonicalProjectionFallbackTest.php

@@ -69,6 +69,7 @@ public function test_projection_fallback_promotes_compact_result_payload(): void
             ->where('published', true)
             ->orderBy('id');
         $wildcard->get();
+        $this->deleteResultOverlays();
 
         $projected = fn() => DB::table('posts')
             ->where('published', true)
@@ -107,6 +108,7 @@ public function test_corrupt_projected_result_falls_back_to_canonical_and_rebuil
             ->where('published', true)
             ->orderBy('id')
             ->get();
+        $this->deleteResultOverlays();
 
         $projected = fn() => DB::table('posts')
             ->where('published', true)