feat(scaffold): idempotency: spec block + scaffolder integration (#174)

[tonydspaniard]

Closes #174. Part of #171. Depends on #172 + #173.

Summary

Spec-driven entry point for the idempotency primitive. A spec carrying:

idempotency:
  ttl: 24h
  scope: tenant
  mode: required

now scaffolds an Action that exposes the policy via a static idempotency() accessor:

public static function idempotency(): array
{
    return ['ttl' => '24h', 'scope' => 'tenant', 'mode' => 'required'];
}

The host application's IdempotencyKeyMiddleware (#173) consumes that metadata via IdempotencyConfiguration to build the per-endpoint policy from spec — no hand-wiring per route.

Pieces

• Altair\Scaffold\Spec\Ast\IdempotencySpec — readonly value object with ttl + scope (default tenant) + mode (default optional).
• Spec.idempotency + Spec::hasIdempotency() — backwards-compatible default null.
• Parser::parseIdempotency() — reads the block; raises SpecParseException on missing ttl.
• Validator::validateIdempotency() — enforces ttl pattern ^[0-9]+(ms|s|m|h|d)$, non-empty scope, and mode enum.
• ActionEmitter — renders the static idempotency() accessor on the generated Action when the spec carries the block. When absent, output is byte-for-byte identical to today's scaffold.
• Altair\Idempotency\Configuration\IdempotencyConfiguration — minimal DI binding: IdempotencyStoreInterface \xe2\x86\x92 InMemoryStore by default; hosts swap to ApcuStore / RedisStore by re-binding.

Why a static accessor and not a base-class slot

The current Altair\Http\Base\Action doesn't carry a middleware-pipeline slot. Modifying it would expand #174 well beyond the issue scope. A static accessor on the generated Action is the smallest invasive change — host middleware reads it from the resolved Action instance via IdempotencyConfiguration and configures the runtime IdempotencyKeyMiddleware accordingly.

The actual route-pipeline auto-wiring is intentionally left as a follow-up because the pattern depends on the host's router and middleware stack (which varies). #176 will document the wiring recipe; once a clear convention emerges across consumers a dedicated issue can tighten the auto-wiring.

Tests (+12)

• IdempotencyParserTest (8) \xe2\x80\x94 happy path, defaults, missing-ttl raise, absent-block null, validator's ttl-pattern / mode / all-units / valid-block / aggregated-exception cases.
• ActionEmitterIdempotencyTest (3) \xe2\x80\x94 accessor absent without block, accessor present + structurally correct with block, generated PHP tokenises cleanly.
• SpecFixture::createUserWithIdempotency() added for downstream reuse.

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 6287 tests (+12 new), 0 new failures
• bin/altair manifest:generate \xe2\x80\x94 clean

Out of scope

• x-altair-idempotency round-trip activation \xe2\x80\x94 x-altair-idempotency round-trip activation: forward emit + reverse import + drift gate #175 (lands next).
• Package doc + benchmark variant \xe2\x80\x94 docs/packages/idempotency.md + tokens-to-ship benchmark variant exercising replay #176.