bug: L1-only mode serializes data unnecessarily (tuples→lists)

[27Bslash6]

Description

Competitive testing reveals that @cache(backend=None) (L1-only mode) serializes data through MessagePack even though there's no L2 backend to send bytes to. This causes type degradation that pure in-memory caches (lru_cache, cachetools) don't have.

Evidence

From tests/competitive/test_head_to_head.py::TestCollectionTypes::test_tuple_preservation:

@cache(backend=None, ttl=300)
def fn(): return (1, 2, 3)

result = fn()
# Expected: (1, 2, 3) — tuple preserved (in-memory, no serialization needed)
# Actual:   [1, 2, 3] — list (MessagePack converted tuple→list)

All three competitors preserve tuples in their in-memory mode:

• functools.lru_cache — stores raw Python objects
• cachetools.TTLCache — stores raw Python objects
• aiocache.SimpleMemoryCache — stores raw Python objects

Impact

• Sets, frozensets, tuples, and nested structures containing them lose type identity
• Users migrating from lru_cache get different behavior
• The comparison doc claims "Same ~50ns performance" vs lru_cache but doesn't disclose this type degradation

Suggested Fix

When backend=None, skip serialization entirely. Store the raw Python object in L1. Serialization is only needed when data crosses process boundaries (L2 backends).

This would make @cache(backend=None) a true drop-in replacement for lru_cache with added TTL, metrics, and unhashable arg support.

Test Evidence

pytest tests/competitive/test_head_to_head.py -k tuple -v — 50/50 passing, documenting current (broken) behavior.

[27Bslash6]

Tradeoff Analysis

After deeper investigation, the proposed fix (skip serialization in L1-only mode) has significant tradeoffs that may make it the wrong approach. Requesting comments before proceeding.

The 5 Tradeoffs

1. The upgrade path breaks silently.

The core pitch is "remove backend=None and you're distributed, zero code changes." But if L1-only stores raw objects while L2 stores serialized bytes:

# Dev (L1-only): returns (1, 2, 3) — tuple ✓
# Prod (L1+L2 Redis): returns [1, 2, 3] — list ✗

Code doing isinstance(result, tuple) or positional tuple unpacking works in dev, breaks in prod. That's worse than being consistently wrong in both environments.

2. Mutation hazard.

Serialization gives you a copy every time. Raw object storage gives you a reference. This is lru_cache's well-known footgun:

result = get_user()
result["scores"].append(4)  # Silently corrupts the cached value
get_user()  # Returns corrupted data

Current cachekit is mutation-safe by design. Skipping serialization reintroduces this class of bug.

3. Encryption invariant breaks.

@cache.secure(backend=None) stores ciphertext in L1 today. Skipping serialization means storing plaintext. The zero-knowledge invariant breaks for L1-only secure mode.

4. L1 backfill inconsistency.

In L1+L2 mode, L2 backfills L1 with deserialized data (tuples already converted to lists). If L1 stores raw objects for direct function calls but deserialized objects for L2 backfills, the same cache key returns different types depending on how it was populated. Debugging nightmare.

5. Current behavior may be correct.

"Your code behaves identically in dev and prod" is arguably the right default. Type degradation is consistent and predictable — you discover it during development, not as a production surprise.

Alternative Approaches

Option	Description	Pros	Cons
A (this issue)	Skip serialization in L1-only	Type preservation, ~50ns perf	Breaks upgrade path, mutation hazard, encryption breaks
B	Keep current behavior, document honestly	Consistent, mutation-safe, upgrade works	Tuples→lists everywhere
C	MessagePack extension types for tuples/sets	Types preserved in ALL modes (L1+L2)	Custom code, cross-SDK interop cost, cache-breaking migration
D	Opt-in raw=True parameter	Users who want lru_cache behavior can get it	More API surface, YAGNI until requested

Current status

• Option B is done: comparison docs updated with honest disclosure of this tradeoff
• 50-test competitive suite (tests/competitive/test_head_to_head.py) documents actual behavior
• This issue remains open for community input on whether Option A, C, or D is worth pursuing

Questions for commenters

1. Have you hit this in practice? Does tuple→list actually break your code?
2. Would you accept the mutation hazard (Option A) for type preservation?
3. Would cross-SDK tuple preservation (Option C) matter to you, or is this Python-only?

[27Bslash6]

Leaning toward Option D (raw=True).

Use case: users who explicitly want lru_cache-like behavior — raw Python object storage, no serialization overhead, full type preservation — and accept the tradeoffs (mutation hazard, types change if backend is added later).

Rough API sketch:

# Default: serialized, mutation-safe, consistent across backends
@cache(backend=None, ttl=300)
def fn(): return (1, 2, 3)  # returns [1, 2, 3]

# Opt-in: raw object storage, lru_cache-like behavior
@cache(backend=None, ttl=300, raw=True)
def fn(): return (1, 2, 3)  # returns (1, 2, 3)

Constraints:

• raw=True only valid with backend=None — raise ValueError if combined with a real backend (can't send raw Python objects over the wire)
• raw=True + encryption=True → ValueError (can't encrypt what you don't serialize)
• Document the mutation hazard prominently
• cache_info() can't report size_bytes in raw mode (no serialized size to measure)

This keeps the safe default, gives power users an escape hatch, and avoids breaking the upgrade path for anyone who doesn't explicitly opt in.

[27Bslash6]

Update: AutoSerializer already solves this for sets, not tuples

Investigation reveals:

# AutoSerializer preserves sets via __set__ type marker
@cache(backend=None, serializer='auto')
def fn(): return {1, 2, 3}
fn(); fn()  # set → set ✓ (roundtrip preserved)

# But NOT tuples — no __tuple__ marker exists
@cache(backend=None, serializer='auto')
def fn(): return (1, 2, 3)
fn(); fn()  # tuple → list ✗ (MessagePack converts)

The AutoSerializer already uses a type-marker pattern for sets/frozensets ({"__set__": True, "value": [...], "frozen": bool}). The same pattern could be applied to tuples ({"__tuple__": True, "value": [...]}).

This means the fix is:

1. Add __tuple__ marker to AutoSerializer._auto_default() and _auto_object_hook()
2. Tuples preserved in ALL modes (L1, Redis, Memcached, File, CachekitIO)
3. No new parameter needed
4. Only affects serializer='auto' — default StandardSerializer stays as-is for cross-language compatibility (other SDKs don't understand __tuple__ markers)
5. No mutation hazard — still serializes, still returns copies

This is cleaner than raw=True. The cross-language tradeoff is explicit: use serializer='auto' for Python-only type fidelity, use serializer='default' for cross-SDK compatibility.

Remaining question: should serializer='auto' become the default for backend=None? That would give L1-only users type preservation out of the box while keeping serializer='default' for distributed backends where cross-SDK matters.