feat(server): idempotency middleware per AdCP #2315 spec

[bokelley]

Closes #182. Server-side counterpart to PR #194 (client-side idempotency).

What

Drop-in decorator for Python sellers so they don't hand-roll the (principal, key, canonical-hash) → cached-response machinery per tool handler.

from adcp.server.idempotency import IdempotencyStore, MemoryBackend

idempotency = IdempotencyStore(
    backend=MemoryBackend(),
    ttl_seconds=86400,
)

class MySeller(ADCPHandler):
    @idempotency.wrap
    async def create_media_buy(self, params, context=None):
        return my_create_logic(params)

    async def get_adcp_capabilities(self, params, context=None):
        caps = build_caps(...)
        caps.adcp.idempotency = idempotency.capability()
        return caps

Spec mapping

Implements the seller side of AdCP #2315 per security.mdx#idempotency:

• Scope lookups by (authenticated_principal, idempotency_key) — security requirement
• Canonical hash via RFC 8785 JCS + SHA-256 over the payload minus the spec's closed exclusion list (idempotency_key, context, governance_context, push_notification_config.authentication.credentials)
• Cache hit + matching hash → return cached response, skip handler
• Cache hit + different hash → raise IdempotencyConflictError before the handler runs (preserves at-most-once)
• Cache miss → run handler, commit (hash, response) to the backend

What ships

New subpackage src/adcp/server/idempotency/:

• canonicalize.py — canonical_json_sha256, strip_excluded_fields, EXCLUDED_FIELDS (closed set). Input payload never mutated.
• backends.py — IdempotencyBackend ABC, MemoryBackend (dict + asyncio.Lock + lazy expiry + sweeper), PgBackend scaffold that raises NotImplementedError with a clear pointer to the follow-up.
• store.py — IdempotencyStore class, @wrap decorator, .capability() returning {\"replay_ttl_seconds\": ttl} for inline capability declaration.

New core dependency: rfc8785 (tiny pure-Python JCS).

Design calls worth flagging for review

• Fail-closed on missing caller_identity: no principal → fall through to the plain handler rather than collapse every buyer into a shared namespace. Degrades the feature but prevents a security regression.
• Deep-copy on put and get: callers who mutate the returned response (adding derived fields, appending to lists) don't poison future replays. Test locks this in (TestCachedResponseImmutability).
• Cache commit after handler returns: MemoryBackend has no transactional relationship to external resources; a crash between handler-success and cache-commit re-executes on retry. Documented. PgBackend follow-up will commit in the handler's transaction.
• Backend put failure: log a WARNING, return the handler's result. Raising would look to the caller like the handler failed → retry → double-execute. Swallowing is wrong. Warning is the honest compromise. Test locks this in.
• TTL bounds: enforced to [3600, 604800] per spec capabilities.idempotency.replay_ttl_seconds (1h–7d).

Tests

38 new tests in tests/test_server_idempotency.py covering:

• Canonicalize: determinism, key-order independence, closed exclusion set lock, nested path stripping, no input mutation, ext preserved in hash
• MemoryBackend: put/get/miss, lazy TTL expiry, per-principal isolation, sweeper, concurrent put under asyncio.gather
• IdempotencyStore.wrap: miss→hit→conflict→fresh-key, per-principal scope, excluded-field change is not a conflict, Pydantic / dict / dict-context inputs, fail-closed when no caller identity
• Instance-method decorator shape (@store.wrap above an async method on a handler class)
• Cached response immutability — caller mutation doesn't poison replays
• Backend put failure logs WARNING and returns handler's response
• Capability fragment + TTL bound validation (low/high/min/max)
• TTL expiry via time-patch

Total: 1483 pytest passing, mypy clean (660 source files), ruff clean on the new code.

Expert review addressed

Code-reviewer flagged three should-fix items; all applied:

• Dead HandlerReturn TypeVar removed
• Cached response deep-copied on put AND get (the shallow-copy-only approach leaked nested-list mutations)
• Backend put failure now logs WARNING with structured context instead of masking as handler failure

Follow-ups (explicitly out of scope)

• PgBackend implementation that commits the cache row in the same SQLAlchemy/asyncpg transaction as the handler's business writes
• Wire the middleware into the AdCP training agent / reference seller so the upstream idempotency storyboard passes end-to-end (currently fails because the reference agent declares the capability but doesn't enforce it — adcp#2346)

Test plan

• pytest tests/ --no-cov -q — 1483 passed
• mypy src/adcp/ — 0 errors, 660 files
• ruff check — clean
• Spec exclusion list locked in a dedicated regression test so future maintainers can't silently broaden it

🤖 Generated with Claude Code