[Feature] Chunked values: setValueChunked() / getValueChunked()

[s2x]

Problem

FDB enforces a hard limit of 100 kB per value (and 10 kB per key). Anything larger fails with value_too_large. Framework integrations we plan (Symfony/Laravel cache stores, session handlers, queue envelopes) regularly produce payloads above 100 kB (serialized objects, rendered HTML), so they need transparent chunking.

Proposal

Add chunking primitives to the library so adapters don't reinvent the wheel:

• Transaction::setValueChunked(string $key, string $value, int $chunkSize = 100_000): void — writes $value split into $chunkSize-byte chunks at ordered sub-keys ($key + tuple suffix per chunk index), clears leftover chunks from a previous larger value in the same transaction (so reads never see stale tails).
• Transaction::getValueChunked(string $key): ?string — reads all chunks in one range read and reassembles; returns null if the key doesn't exist.
• Snapshot-read variants if applicable.

Limits / cap

• Chunked write happens in a single transaction → atomicity is preserved, but the 10 000 000 B mutation budget applies: cap the assembled value at 8 MB (safe margin for key/tuple overhead, ~80 chunks) and throw a descriptive exception above it.
• Reads use a range read — effectively bounded by the 5 s transaction limit only; the 8 MB cap keeps writes and reads symmetric.
• Plain (non-chunked) set()/get() behavior unchanged.

Acceptance criteria

• setValueChunked() / getValueChunked() on Transaction (+ snapshot variants if applicable)
• Round-trip tests: value exactly at chunk boundary, value spanning multiple chunks, overwrite from larger to smaller value (stale chunk clearing), value > 8 MB rejected with clear error
• Integration tests against the Docker cluster (values > 100 kB, multi-chunk)
• Unit tests (chunk index packing via the tuple layer, no key > 10 kB)
• docs/ + CHANGELOG entry

Context

Prep work for the planned Symfony bundle / Laravel package (cache store, session handler, queue transport) discussed in the team; those adapters will all need this.

[s2x]

Design decisions for chunked values (follow-up to this issue)

Based on the discussion, here are the concrete design decisions we'd like to apply before implementation.

1. Chunk key format (storage format — de facto API, frozen)

• Chunks: $key . "\x00" . Tuple::pack([$generation, $chunkIndex]) (int index, starting at 0)
• Metadata key: $key . "\x00" . "\x00" (tuple-null encoding — sorts before all chunk keys, unreachable through the library's public API: Tuple / Subspace / Directory)
• The \x00 separator guarantees no collision with user text suffixes (e.g. $key . "abc")
• Format marked @internal — any change requires a migration

2. Metadata header (magic header)

Value of the meta key:

"FDBCK1" (6 B magic) | total_length (8 B, big-endian) | chunk_count (4 B) | generation (4 B)

This resolves:

• distinguishing "key does not exist" (null) from an empty value "" (meta with chunk_count = 0)
• detecting foreign/overwritten data → ChunkedValueCorruptedException instead of silently returning garbage
• atomic swap in multi-transaction mode (generation acts as the active-generation pointer)
• one extra mutation per write also creates a conflict range on the meta key

3. Overwriting with fewer chunks (stale tail)

• Atomic mode: clearRange over the whole chunk key space + write new chunks + meta in a single transaction — the stale tail disappears atomically
• Multi-transaction mode: write new chunks under generation + 1 without touching the old ones; a final micro-transaction swaps only the meta; old generations are cleaned up lazily on the next write

4. Exceptions (dedicated hierarchy)

• ChunkedValueTooLargeException extends \RuntimeException (fields: valueSize, maxSize) — thrown before any mutation when exceeding the 8 MB cap in atomic mode
• ChunkedValueCorruptedException extends \RuntimeException — broken/missing magic or missing chunks for the active generation
• Both are precisely catchable by future framework adapters

Note: nothing is byte-wise "impossible" to produce with plain set(), since it accepts arbitrary binary strings. The guarantee is structural: the \x00-namespaced keys are unreachable through the public tuple/subspace/directory API, and the magic header makes any tampering immediately detectable instead of silently misbehaving.

5. Two write modes

Transaction::setValueChunked(string $key, string $value, int $chunkSize = 100_000, bool $atomic = true): void

• atomic: true (default): single transaction, 8 MB cap, full atomicity (as proposed in the issue)
• atomic: false: generation scheme + meta swap — no 8 MB cap, bounded only by practical limits; readers see either the old or the new generation via the meta swap

6. Full API

Transaction::setValueChunked(string $key, string $value, int $chunkSize = 100_000, bool $atomic = true): void
Transaction::getValueChunked(string $key): ?string   // + snapshot variant
Transaction::deleteValueChunked(string $key): void

Read semantics:

• key does not exist (no meta) → null
• meta with chunk_count = 0 → "" (empty string)
• meta present but magic mismatch / missing chunks → ChunkedValueCorruptedException

null for a miss keeps parity with get() and with cache-adapter contracts (no exception handling in the hot path). Deletion is a single clearRange($key . "\x00", $key . "\x01") — removes meta, all chunks and all generations in one cheap mutation.

7. Explicitly out of scope

• No TTL in this layer — it stays generic. Expiration will be emulated lazily by future Symfony/Laravel adapters (timestamp in the payload + lazy delete + probabilistic sweep)
• Mixing plain set() and setValueChunked() on the same key = unsupported (documented); watch() and atomic ops do not observe chunked values

8. Extended acceptance criteria (additions)

• Round-trip of "" → read back as "" (not null)
• Overwrite with fewer chunks (stale tail invisible) — both modes
• 8 MB cap and chunkSize ≤ 100 000 validated before any mutation
• Foreign/tampered data → ChunkedValueCorruptedException
• Both write modes produce identical read results via the same read path
• Text suffixes ($key . "abc") never collide with the chunk namespace
• deleteValueChunked() removes meta + all chunks + all generations

[s2x]

Implemented in #118 (branch feat/115-chunked-values), following the design decisions from the comment above: Chunk\ChunkKeyCodec (frozen storage format), Transaction::setValueChunked() (atomic, 8 MB cap), Database::setValueChunked(..., atomic: bool) (generation scheme for values above the cap), ReadTransaction::getValueChunked() (snapshot-capable, null/""/ChunkedValueCorruptedException semantics) and deleteValueChunked() (single range clear). Reuses the @internal MutationBudget from #116; the \x00 key-space codec stays private to this layer. Unit + integration tests, docs/chunked-values.md and CHANGELOG entry included. PR description carries the full summary.

[s2x]

Implemented in #118, squash-merged to master (c1838c9).

What was added:

• src/Chunk/ChunkKeyCodec.php (@internal) — frozen storage format: chunk keys $key . "\x00" . Tuple::pack([generation, index]), metadata key $key . "\x00\x00", namespace range [$key . "\x00", $key . "\x01"), magic-signed 22-byte metadata record (FDBCK1 + total length + chunk count + generation).
• Transaction::setValueChunked(key, value, chunkSize = 100000) — atomic single-transaction write (namespace clear + chunk writes + metadata). Capped at 8,000,000 B (MutationBudget::SPLIT_TARGET_BYTES); above the cap ChunkedValueTooLargeException is thrown before any mutation.
• ReadTransaction::getValueChunked(key): ?string — one range read; snapshot reads work. null for missing key, "" for empty value, ChunkedValueCorruptedException on malformed metadata / missing chunks / wrong total length.
• Transaction::deleteValueChunked(key) — one range clear removes meta + all chunks + all generations.
• Database::setValueChunked(..., atomic: true|false) — atomic mode via transact(), or generation-swap mode without a size cap (chunk groups committed separately, final micro-transaction swaps metadata and cleans up the previous generation; readers always see old or new value in full).
• Shared @internal MutationBudget accounting (from feat(#116): setBatch() helper with mutation-budget enforcement #117); docs in docs/chunked-values.md; changelog entry under [Unreleased] / Added.

Tests: unit (610 OK, incl. new ChunkKeyCodecTest) + integration (308 OK, incl. new ChunkedValuesTest — round trips, overwrite larger→smaller, delete, cap rejection, non-atomic 12 MB write, generation swap cleanup, corruption detection).