CacheLayer 4.0 security and correctness hardening

.github/ISSUE_TEMPLATE/regression_report.yml

@@ -46,6 +46,6 @@ body:
     attributes:
       label: Environment details
       description: PHP version, Composer version, OS, CI provider (if relevant).
-      placeholder: PHP 8.3, Composer 2.9, Ubuntu 24.04...
+      placeholder: PHP 8.4, Composer 2.10, Ubuntu 24.04...
     validations:
       required: true

.github/workflows/release-verification.yml

@@ -0,0 +1,256 @@
+name: "Release Verification"
+
+on:
+  pull_request:
+    branches: [ "main", "master", "develop", "development" ]
+  push:
+    branches: [ "main", "master" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  core-platform:
+    name: Core smoke - PHP ${{ matrix.php }} - ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ "8.4", "8.5" ]
+        os: [ ubuntu-24.04, windows-latest ]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:v2
+          extensions: mbstring, mongodb, pdo, pdo_sqlite, opcache
+          coverage: none
+      - run: composer install --no-dev --no-interaction --prefer-dist --no-progress --classmap-authoritative --ignore-platform-req=ext-mongodb
+      - run: composer check-platform-reqs --no-dev
+      - name: Core smoke without CLI OPcache
+        run: php -d error_reporting=E_ALL -d opcache.enable_cli=0 tools/release/core-smoke.php
+      - name: Core smoke with CLI OPcache
+        run: php -d error_reporting=E_ALL -d opcache.enable_cli=1 tools/release/core-smoke.php
+
+  clean-consumer:
+    name: Clean no-dev consumer - PHP ${{ matrix.php }}
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ "8.4", "8.5" ]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:v2
+          coverage: none
+      - name: Resolve candidate in fresh consumer
+        working-directory: tools/release/consumer
+        run: composer update --no-dev --no-interaction --prefer-dist --no-progress
+      - name: Reinstall locked candidate as production-only
+        working-directory: tools/release/consumer
+        shell: bash
+        run: rm -rf vendor && composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction --no-progress
+      - name: Smoke production consumer
+        working-directory: tools/release/consumer
+        run: php -d error_reporting=E_ALL smoke.php
+
+  runwire-consumer:
+    name: Runwire 2.1 consumer - PHP ${{ matrix.php }} - ${{ matrix.dependencies }}
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ "8.4", "8.5" ]
+        dependencies: [ lowest, stable ]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:v2
+          extensions: pdo, pdo_sqlite
+          coverage: none
+      - name: Resolve CacheLayer with Runwire 2.1
+        working-directory: tools/release/runwire-consumer
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ "${{ matrix.dependencies }}" = "lowest" ]; then
+            composer update --prefer-lowest --prefer-stable --no-interaction --prefer-dist --no-progress
+          else
+            composer update --prefer-stable --no-interaction --prefer-dist --no-progress
+          fi
+          composer check-platform-reqs
+      - name: Run Runwire integration smoke
+        working-directory: tools/release/runwire-consumer
+        run: php -d error_reporting=E_ALL smoke.php
+      - name: Run matched Runwire certification workload
+        working-directory: tools/release/runwire-consumer
+        run: php -d error_reporting=E_ALL certify.php
+      - name: Run persistent-worker Runwire soak
+        working-directory: tools/release/runwire-consumer
+        run: php -d error_reporting=E_ALL soak.php
+
+  psr-contracts:
+    name: Independent PSR-6 / PSR-16 contracts
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          tools: composer:v2
+          coverage: none
+      - name: Install independent consumer
+        working-directory: tools/release/psr-consumer
+        run: composer update --no-interaction --prefer-dist --no-progress --prefer-stable
+      - name: Materialize independent integration fixtures
+        working-directory: tools/release/psr-consumer
+        shell: bash
+        run: |
+          mkdir -p tests
+          cat > tests/Psr6MemoryIntegrationTest.php <<'PHP'
+          <?php
+          declare(strict_types=1);
+
+          use Cache\IntegrationTests\CachePoolTest;
+          use Infocyph\CacheLayer\Cache\Cache;
+          use Infocyph\CacheLayer\Cache\CacheOptions;
+          use Psr\Cache\CacheItemPoolInterface;
+
+          final class Psr6MemoryIntegrationTest extends CachePoolTest
+          {
+              protected array $skippedTests = [
+                  'testBasicUsageWithLongKey' => 'CacheLayer intentionally supports 64-character logical keys, satisfying the PSR minimum.',
+              ];
+
+              public function createCachePool(): CacheItemPoolInterface
+              {
+                  return Cache::sqlite(
+                      'psr6',
+                      sys_get_temp_dir() . '/cachelayer-psr6-' . getmypid() . '.sqlite',
+                      new CacheOptions(allowObjects: true),
+                  );
+              }
+          }
+          PHP
+
+          cat > tests/Psr16MemoryIntegrationTest.php <<'PHP'
+          <?php
+          declare(strict_types=1);
+
+          use Cache\IntegrationTests\SimpleCacheTest;
+          use Infocyph\CacheLayer\Cache\Cache;
+          use Infocyph\CacheLayer\Cache\CacheOptions;
+          use Psr\SimpleCache\CacheInterface;
+
+          final class Psr16MemoryIntegrationTest extends SimpleCacheTest
+          {
+              protected array $skippedTests = [
+                  'testBasicUsageWithLongKey' => 'CacheLayer intentionally supports 64-character logical keys, satisfying the PSR minimum.',
+              ];
+
+              public function createSimpleCache(): CacheInterface
+              {
+                  return Cache::sqlite(
+                      'psr16',
+                      sys_get_temp_dir() . '/cachelayer-psr16-' . getmypid() . '.sqlite',
+                      new CacheOptions(allowObjects: true),
+                  );
+              }
+          }
+          PHP
+      - name: Run upstream integration suites
+        working-directory: tools/release/psr-consumer
+        run: vendor/bin/phpunit tests
+
+  docs:
+    name: Documentation warnings as errors
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --disable-pip-version-check -r docs/requirements.txt
+      - run: python -m sphinx -W --keep-going -b html docs docs/_build/html
+
+  redis-cluster:
+    name: Real Redis Cluster
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          tools: composer:v2
+          extensions: redis
+          coverage: none
+      - run: composer install --no-dev --no-interaction --prefer-dist --no-progress --classmap-authoritative
+      - name: Start three-node Redis Cluster
+        shell: bash
+        run: |
+          set -euo pipefail
+          for port in 7001 7002 7003; do
+            docker run -d --name "cachelayer-redis-$port" --network host redis:8.10-alpine redis-server --port "$port" --cluster-enabled yes --cluster-config-file "nodes-$port.conf" --cluster-node-timeout 5000 --cluster-announce-ip 127.0.0.1 --cluster-announce-port "$port" --cluster-announce-bus-port "$((port + 10000))" --appendonly no --protected-mode no
+          done
+          for attempt in {1..60}; do
+            if docker exec cachelayer-redis-7001 redis-cli -p 7001 ping | grep -q PONG; then break; fi
+            sleep 1
+          done
+          docker exec cachelayer-redis-7001 redis-cli --cluster create 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 --cluster-replicas 0 --cluster-yes
+          for attempt in {1..60}; do
+            if docker exec cachelayer-redis-7001 redis-cli -c -p 7001 cluster info | tr -d '\r' | grep -q "cluster_state:ok"; then
+              break
+            fi
+            sleep 1
+          done
+          docker exec cachelayer-redis-7001 redis-cli -c -p 7001 cluster info | tr -d '\r' | grep -q "cluster_state:ok"
+      - name: Exercise CacheLayer against real Redis Cluster
+        env:
+          CACHELAYER_REDIS_CLUSTER_SEEDS: "127.0.0.1:7001,127.0.0.1:7002,127.0.0.1:7003"
+        run: php -d error_reporting=E_ALL tools/release/redis-cluster-smoke.php
+      - if: always()
+        shell: bash
+        run: docker rm -f cachelayer-redis-7001 cachelayer-redis-7002 cachelayer-redis-7003 >/dev/null 2>&1 || true
+
+  scylla-cql:
+    name: Real Scylla CQL
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          tools: composer:v2
+          coverage: none
+      - run: composer install --no-dev --no-interaction --prefer-dist --no-progress --classmap-authoritative
+      - name: Start ScyllaDB CQL service
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker run -d --name cachelayer-scylla -p 9042:9042 scylladb/scylla:2026.2 --reactor-backend epoll --smp 1 --memory 1G --overprovisioned 1 --developer-mode=1
+          for attempt in {1..120}; do
+            if docker exec cachelayer-scylla cqlsh -e "SELECT release_version FROM system.local;" >/dev/null 2>&1; then break; fi
+            sleep 2
+          done
+          docker exec cachelayer-scylla cqlsh -e "CREATE KEYSPACE IF NOT EXISTS cachelayer WITH replication = {'class':'NetworkTopologyStrategy','datacenter1':1};"
+      - name: Install pinned Scylla PHP CQL driver
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y libuv1 libgmp10
+          mkdir -p .ci/scylla-driver
+          curl -fsSL https://github.com/he4rt/scylladb-php-driver/releases/download/v1.5.1/manylinux_2_28_x86_64-php8.4-nts-cassandra.tar.gz -o .ci/scylla-driver/driver.tar.gz
+          tar -xzf .ci/scylla-driver/driver.tar.gz -C .ci/scylla-driver
+          php -d "extension=$PWD/.ci/scylla-driver/cassandra.so" -r 'if (!class_exists("Cassandra")) { throw new RuntimeException("Cassandra extension did not load."); }'
+      - name: Exercise CacheLayer against real CQL
+        run: php -d error_reporting=E_ALL -d "extension=$PWD/.ci/scylla-driver/cassandra.so" tools/release/scylla-cql-smoke.php
+      - if: always()
+        run: docker rm -f cachelayer-scylla >/dev/null 2>&1 || true

.github/workflows/security-standards.yml

@@ -5,18 +5,28 @@ on:
     - cron: "0 0 * * 0"
   push:
     branches: [ "main", "master" ]
+    tags: [ "v*", "[0-9]*" ]
   pull_request:
     branches: [ "main", "master", "develop", "development" ]
 
 jobs:
   phpforge:
+    if: github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/')
     uses: infocyph/phpforge/.github/workflows/security-standards.yml@main
     permissions:
       security-events: write
       actions: read
       contents: read
     with:
-      php_extensions: "apcu, mbstring, memcached, mongodb, pdo, pdo_mysql, pdo_pgsql, pdo_sqlite, redis, sysvshm"
+      php_extensions: "apcu, mbstring, memcached, mongodb, pcntl, pdo, pdo_mysql, pdo_pgsql, pdo_sqlite, redis, sysvshm"
       fail_on_skipped_tests: true
-      integration_services: '["mysql","postgres","sqlite","redis","valkey","memcached","scylladb"]'
-      service_topologies: '{}'
+      integration_services: '["mysql","mariadb","postgres","sqlite","mongodb","redis","valkey","memcached","scylladb"]'
+      service_topologies: '{"mongodb":"replica-set"}'
+
+  release:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    uses: infocyph/phpforge/.github/workflows/release.yml@main
+    permissions:
+      contents: write
+    secrets:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}

README.md

@@ -6,7 +6,7 @@
 ![Packagist Version](https://img.shields.io/packagist/v/infocyph/CacheLayer)
 ![Packagist PHP Version](https://img.shields.io/packagist/dependency-v/infocyph/CacheLayer/php)
 
-CacheLayer is a PHP 8.3+ caching toolkit built around four deliberately separate concerns:
+CacheLayer is a PHP 8.4+ caching toolkit built around four deliberately separate concerns:
 
 ```text
 CacheLayer
@@ -34,6 +34,8 @@ composer require infocyph/cachelayer
 
 Choose extensions and client packages only for the backends you use: APCu, Redis/Valkey, Memcached, PDO, SysV shared memory, MongoDB, or Cassandra/ScyllaDB.
 
+For 3.x upgrades, read `docs/upgrade-4.0.rst` before deployment. 4.0 raises the minimum runtime to PHP 8.4 and intentionally changes serialization, storage identity, cursor, counter, and cache-contract behavior.
+
 ## Cache
 
 ```php
@@ -204,7 +206,7 @@ function createCache(string $integrityKey): Cache
 }
 ```
 
-Records use only the CacheLayer v2 markers `cl2:`, `cl2-gz:`, and `cl2-sig:`. Compression is threshold-based and retained only when smaller. HMAC verification, payload bounds, bounded decompression, and deserialization policy are isolated per cache instance. Corrupt payloads are safe misses.
+Records use the plain/compressed v2 markers `cl2:` and `cl2-gz:`, plus the identity-bound signed marker `cl3-sig:`. Compression is threshold-based and retained only when smaller. HMAC verification, payload bounds, bounded decompression, and deserialization policy are isolated per cache instance. Corrupt payloads are safe misses.
 
 Construction and configuration errors throw. Runtime backend failures default to fail-open: reads become misses, writes/deletes return `false`, and `backend_failure` is recorded. Set `failOpen: false` to propagate runtime failures. Pass deploy-varying values from the application's composition root; CacheLayer never reads process environment state.
 
@@ -235,11 +237,19 @@ $runtime->consume();
 
 Failed local invalidation stops consumption without advancing the cursor; operators can repair the cause and retry. A poison event can only be skipped explicitly with `skipEventAfterClear()`, which clears the local namespace before advancing. Plain key invalidation cannot fence an in-flight resolver, so mutable read-through data that requires ordering should also use a tag generation. It does not replicate values and is not a distributed lock, session store, or counter system.
 
+## Runwire 2.1 integration
+
+CacheLayer 4.0 ships optional Runwire 2.1 integration without making Runwire a core dependency. A framework shares its active `RuntimeContext` at worker/application bootstrap and the current `RequestContext` / `CoroutineScope` at the request or task boundary. CacheLayer then uses relevant capabilities automatically; when Runwire is absent, inactive, or missing a capability, the ordinary CacheLayer path remains in use.
+
+Runwire keeps ownership of listeners, workers, supervisors, and event loops. `RunwireWorkerIntegration` can place bounded Cluster invalidation consumption and Node SQLite maintenance inside a host-provided task/service worker scope; CacheLayer never starts background work merely because Runwire is installed. Synchronous backend calls remain synchronous.
+
+Concurrent persistent Runwire requests receive request-owned memoizer state. If a concurrent runtime is bound without a shared request scope, memoization helpers bypass the process-global cache rather than risk cross-request leakage. See `docs/runwire.rst` and the executable `examples/runwire-invalidation-worker.php`.
+
 ## Atomic counters and memoization
 
-`AtomicCounters` uses an `AtomicCounterStoreInterface`; Redis/Valkey is the distributed implementation. Counters are never emulated with cache `get()` plus `set()`. Atomic counters are separate from `Cache::atomic()`: counters mutate numeric state, while the cache capability provides conditional claim/replace/consume primitives for encoded cache records.
+`AtomicCounters` uses an `AtomicCounterStoreInterface`; Redis/Valkey is the distributed implementation. Counters are never emulated with cache `get()` plus `set()`. They live in a dedicated `cachelayer:counter:<namespace>:` keyspace, so ordinary cache `clear()` does not reset them, and the Lua update returns an exact decimal string before PHP range validation. Atomic counters are separate from `Cache::atomic()`: counters mutate numeric state, while the cache capability provides conditional claim/replace/consume primitives for encoded cache records.
 
-The `memoize()`, `remember(object: ...)`, and `once()` helpers plus `MemoizeTrait` provide bounded process-local memoization. Their state survives requests in persistent workers until evicted or reset with `flush_memoizers()`; call that reset at request boundaries when cross-request reuse is not intended. They are independent of persistent backend caching.
+The `memoize()`, `remember(object: ...)`, and `once()` helpers plus `MemoizeTrait` provide bounded process-local memoization on the normal path. With an active Runwire request scope they use request-owned memoizers; a concurrent persistent Runwire runtime without a shared request scope bypasses global memoization rather than leaking state between requests. `flush_memoizers()` resets the currently owned memoizer scope. They are independent of persistent backend caching.
 
 ## Metrics and benchmarks
 

benchmarks/CachePolicyBench.php

@@ -36,7 +36,13 @@ public function benchCompressedCodec(array $params): int
     public function benchHmacCodec(): int
     {
         $codec = new CachePayloadCodec(new CacheOptions(integrityKey: 'benchmark-secret'));
-        $record = $codec->decode($codec->encode($this->payload, null));
+        $payload = $codec->encode(
+            $this->payload,
+            null,
+            storageIdentity: 'benchmark',
+            key: 'payload',
+        );
+        $record = $codec->decode($payload, 'benchmark', 'payload');
 
         return strlen((string) $record?->value);
     }

composer.json

@@ -34,14 +34,15 @@
         }
     ],
     "require": {
-        "php": ">=8.3",
+        "php": ">=8.4",
         "opis/closure": "^4.5",
         "psr/cache": "^3.0",
         "psr/simple-cache": "^3.0"
     },
     "require-dev": {
         "infocyph/phpforge": "dev-main@dev",
-        "mongodb/mongodb": "^1.20 || ^2.0"
+        "infocyph/runwire": "2.1",
+        "mongodb/mongodb": "*"
     },
     "suggest": {
         "ext-apcu": "For APCu-based caching (in-memory, per-process)",
@@ -55,6 +56,7 @@
         "ext-pdo_sqlite": "For default SQLite usage via Cache::pdo(...) or Cache::sqlite(...)",
         "ext-redis": "For Redis-based caching (persistent, networked)",
         "ext-sysvshm": "For shared-memory caching via SharedMemoryCacheAdapter",
+        "infocyph/runwire": "For optional Runwire 2.1 request/task isolation and worker-owned invalidation/maintenance integration",
         "mongodb/mongodb": "For MongoDB caching via MongoDbCacheAdapter"
     },
     "minimum-stability": "stable",