CacheLayer 3.3: add optional atomic cache capabilities

[abmmhasan]

Summary

Add a strict optional atomic cache capability without widening CacheInterface or pretending unsupported adapters are atomic.

Type

• New feature
• Security or reliability
• Documentation or examples

Behavior and Compatibility

• New behavior was introduced
• Public API or documented behavior changed
• Existing cache interfaces remain backward compatible

Atomic contract

Consumers discover the capability with Cache::atomic().

Supported operations:

• setIfAbsent() — one-winner conditional insert with TTL in the same atomic backend operation
• getAndDelete() — one-consumer atomic read-and-delete

Generic value-level CAS is intentionally excluded from 3.3. CacheLayer values may be serialized, compressed, integrity-protected, tagged and TTL-bearing; a portable CAS API would need a separate representation/version contract to avoid backend-dependent semantics.

Supported adapters

• Array memory — process-local
• SharedMemory — host-local/cross-process through the adapter's existing exclusive lock
• Redis
• Valkey
• Redis Cluster — same-slot generation-aware Lua path
• MongoDB — unique _id claim and atomic find-and-delete

Unsupported adapters return null from Cache::atomic() rather than emulating atomicity with read-then-write sequences.

Additional cleanup

• use XXH128 for non-cryptographic PDO advisory-lock key derivation
• use XXH128 for SharedMemory owner identity derivation
• document backend scope, fail-open behavior, dedicated coordination-key guidance and Redis Cluster eval() requirement

Validation

• composer ic:ci — GitHub Security & Standards PR run in progress

The repository workflow runs PHP 8.4/8.5 stable + prefer-lowest QA, PHPStan/Psalm, clean production install and configured integration services. Skipped tests are forbidden.

Checklist

• The change is focused and excludes unrelated modifications.
• Tests cover new, corrected and regression-prone behavior.
• Public API and backward-compatibility implications were considered.
• Documentation, examples and type information were updated where required.
• No credentials, secrets, personal data or sensitive debug output are included.
• The implementation does not emulate atomic semantics on unsupported stores.