fix(middleware): skip idempotency cache for mutable error codes (BUG-API-238)

[mastermanas805]

Summary

BUG-API-238 — the free-tier recycle gate emits 402 `free_tier_recycle_requires_claim` with a `claim_url` the user can act on in 30 seconds. Pre-fix the 402 was written to the explicit-key 24h cache, so this sequence stranded the agent on a stale failure:

1. Agent POST `/db/new` with `Idempotency-Key: K1` → 402 (cached against K1).
2. User follows `claim_url`, claims with email (clears the gate state).
3. Agent retries POST `/db/new` with `K1` → replays the cached 402 — even though a fresh handler call would succeed.

The 24h cache TTL is the Stripe contract — same key replays the same response — but it presumes a STABLE outcome. A 402 that flips when the user takes a 30-second action is not stable.

Fix

• `mutableErrorCodes` registry (currently `{ free_tier_recycle_requires_claim }`) listing error codes whose 4xx resolution can flip inside the cache TTL.
• `shouldCacheResponse(status, body, ct)` helper. Defers to caching for success + non-JSON + stable 4xx; skips for `body.error` ∈ mutable map.
• Wired into BOTH explicit-key (24h TTL) and fingerprint-fallback (120s) cache-write paths so the bypass is symmetric.

What did NOT change

• Stripe-shape contract for stable outcomes preserved — `quota_exceeded`, `upgrade_required`, `provision_limit_reached`, `idempotency_key_conflict` etc. all still cache.
• No new endpoints, no new fields, no auth changes.
• Response shape unchanged — only the cache-write decision flips.

Surface checklist (rule 22)

• ✅ `api/internal/middleware/idempotency.go` — helper + 2 wires
• ✅ `api/internal/middleware/idempotency_mutable_cache_test.go` — new regression
• ✅ dashboard / marketing / OpenAPI — no surface change

Coverage block

```
Symptom: Idempotent retry replays stale 402 after user clears recycle gate
Enumeration: rg -F 'rdb.Set(context.Background(), cacheKey' internal/middleware/idempotency.go
Sites found: 2 cache-write paths (explicit + fingerprint)
Sites touched: 2 / 2
Coverage test: TestShouldCacheResponse_MutableErrorsSkipCache iterates the LIVE
mutableErrorCodes map (rule 18 — registry-iterating, not hand-typed);
TestIdempotency_RecycleGate402_SourceAssertion static-grep that BOTH
branches invoke shouldCacheResponse (rule 16 — two emitters of one bug)
Live verified: post-merge — see verify-plan below
```

Local gate

• `go build ./...` ✅
• `go vet ./...` ✅
• `go test ./internal/middleware/` ✅ (full suite, 6.3s)

Live verify plan (post-merge)

```bash
curl https://api.instanode.dev/healthz | jq .commit_id # must match merge SHA

1. POST /db/new with explicit Idempotency-Key as anon user that's already triggered the gate

2. Confirm 402; confirm X-Idempotent-Replay header NOT present on subsequent retry

3. Successful claim, retry again — confirm fresh 201 instead of stale 402

```

🤖 Generated with Claude Code