feat(idempotency): univeros/idempotency — storage contract + adapters (#172)

[tonydspaniard]

Closes #172. Part of #171.

Summary

Adds the storage layer the rest of the Idempotency-Key epic builds on: IdempotencyStoreInterface + StoredResponse value object + three adapters (InMemory / APCu / Redis). New sub-package univeros/idempotency mirrors the layout of univeros/cookie, univeros/session, etc.

Contract

interface IdempotencyStoreInterface
{
    public function claim(string $key, string $requestHash, int $ttlSeconds): ?StoredResponse;
    public function complete(string $key, StoredResponse $response, int $ttlSeconds): void;
    public function release(string $key): void;
    public function get(string $key): ?StoredResponse;
}

claim() is the atomic primitive — null = caller owns the key and must execute, StoredResponse with inProgress=true = another caller already claimed, StoredResponse with inProgress=false = cached response ready to replay.

Adapters

Adapter	Atomic claim primitive	Use case
InMemoryStore	Process-local array + injectable clock	Tests, single-worker scripts
ApcuStore	apcu_add (insert-only)	Single-host production
RedisStore	SET key value NX EX ttl	Multi-host production

ApcuStore throws at construction time when ext-apcu is unavailable; RedisStore accepts a pre-configured \Redis client so connection lifecycle stays the host's responsibility. Both expose a configurable keyPrefix (default altair.idem.) so multiple apps sharing one backend don't collide.

StoredResponse

Final readonly value object with toArray/fromArray + toJson/fromJson. Named constructors StoredResponse::inProgress() / StoredResponse::completed() keep call sites readable. Malformed header rows on hydration are dropped rather than thrown so replay stays robust against partial stored writes.

Tests

26 new across tests/Idempotency/Storage/:

• StoredResponseTest — round-trip via array + JSON, missing-field rejection, malformed-input rejection, header-row sanitisation.
• InMemoryStoreTest — claim / complete / release / get + lazy expiry via the injectable clock.
• ApcuStoreTest — skipped when ext-apcu (CLI-enabled) is absent; otherwise covers fresh-claim, concurrent-claim, complete-then-get, release, and per-prefix namespace isolation.
• RedisStoreTest — skipped when ext-redis is absent or no Redis is reachable; uses db 15 with flushDB cleanup so it doesn't trample real data.

CI has ext-redis; APCu CLI-enabled is typically not provisioned, so the APCu suite will skip there too \xe2\x80\x94 unit logic is identical to InMemoryStore and is exercised by it.

Out of scope (per #171)

• The PSR-15 middleware that drives the store \xe2\x80\x94 IdempotencyKeyMiddleware: PSR-15 middleware with request-hash + in-progress lifecycle #173.
• The idempotency: spec block \xe2\x80\x94 idempotency: spec block + scaffolder integration (AST + parser + validator + emitter wiring) #174.
• The x-altair-idempotency round-trip activation \xe2\x80\x94 x-altair-idempotency round-trip activation: forward emit + reverse import + drift gate #175.
• The package doc + benchmark variant \xe2\x80\x94 docs/packages/idempotency.md + tokens-to-ship benchmark variant exercising replay #176.

Test plan

• composer cs \xe2\x80\x94 green
• composer stan \xe2\x80\x94 green
• composer rector (full tree, no cache) \xe2\x80\x94 green
• composer test \xe2\x80\x94 6255 tests (+26 new), 22 skipped (12 pre-existing env + 10 new APCu/Redis gated), 5 pre-existing env errors unchanged
• bin/altair manifest:generate \xe2\x80\x94 clean; .agent/packages/idempotency.md lands automatically