docs(idempotency): docs/packages/idempotency.md + tokens-to-ship benchmark variant (#176)

[tonydspaniard]

Closes #176. Closes epic #171.

Summary

Wraps the idempotency epic with the doc + benchmark surfaces the rest of the project relies on. With this merged, every consumer of univeros/idempotency lands on a working pattern, and the framework's position vs. hand-rolled / third-party is measurable rather than rhetorical.

What landed

docs/packages/idempotency.md

Full reference matching the docs/packages/scaffold.md template:

• Introduction \xe2\x80\x94 the gap (Laravel/Symfony/Slim ship no native primitive), the Stripe pattern, the agent-era problem
• Installation + system requirements
• Quick start \xe2\x80\x94 spec block, bin/altair spec:scaffold, host wiring, curl-replay demo
• Storage adapter trade-off matrix
• Full behaviour matrix (the canonical reference)
• Round-trip semantics + link to docs/openapi/extensions.md + docs/openapi/roundtrip.md
• What does not round-trip yet (webhook idempotency, sagas, cross-region, streaming)
• Testing recipes for application tests

src/Altair/Idempotency/README.md

Slim package README pointing at the docs page. Same shape as the rest of the sub-packages' READMEs.

benchmarks/tokens-to-ship/task-idempotency.md + fixture

Third variant of the tokens-to-ship benchmark (after task.md and task-import.md). Frozen prompt + acceptance suite + fixture measure the cost of delivering a correctly idempotent endpoint per arm \xe2\x80\x94 the canonical realistic mutating-API task in 2026.

Acceptance delta vs. task.md:

• POST /posts with Idempotency-Key twice (same body) \xe2\x86\x92 both return 201 with the same id; second has Idempotency-Replayed: true.
• Same key, different body \xe2\x86\x92 409.
• Header absent \xe2\x86\x92 400.
• Same three checks apply to PUT /posts/{id}.

Fixture: benchmarks/tokens-to-ship/fixtures/posts-idempotent.openapi.yaml extends the existing Posts shape with x-altair-idempotency on POST + PUT plus 400 / 409 response descriptions.

Verified end-to-end

bin/altair openapi:import benchmarks/tokens-to-ship/fixtures/posts-idempotent.openapi.yaml --scaffold --persistence=cycle

Produces 5 specs + 38 scaffolded files. The idempotency: block is correctly inserted on api/posts/create.yaml and api/posts/update.yaml.

bin/altair openapi:roundtrip benchmarks/tokens-to-ship/fixtures/posts-idempotent.openapi.yaml

Reports clean: 5 operation(s) round-tripped without drift.

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 6292 tests; no new tests (docs-only change), 0 new failures
• bin/altair manifest:generate \xe2\x80\x94 clean
• Real-CLI smoke verified above

Epic close

#171 is fully delivered:

• univeros/idempotency: storage contract + adapters (InMemory, APCu, Redis) #172 \xe2\x80\x94 storage contract + adapters (bbc50bf)
• IdempotencyKeyMiddleware: PSR-15 middleware with request-hash + in-progress lifecycle #173 \xe2\x80\x94 PSR-15 middleware + hasher (3dae23e)
• idempotency: spec block + scaffolder integration (AST + parser + validator + emitter wiring) #174 \xe2\x80\x94 idempotency: spec block + scaffolder (5a162af)
• x-altair-idempotency round-trip activation: forward emit + reverse import + drift gate #175 \xe2\x80\x94 x-altair-idempotency round-trip activation (42c3720)
• docs/packages/idempotency.md + tokens-to-ship benchmark variant exercising replay #176 \xe2\x80\x94 docs + benchmark (this PR)