Skip to content

bug(idempotency): is_wrapped() misses @store.wrap under any outer decorator, so boot validation rejects a wired platform #1295

Closed

Description

@bokelley

Summary

On 8.0.0, is_wrapped(fn) returns True only when fn itself is the closure that IdempotencyStore.wrap returned (adcp/server/idempotency/store.py:89-99). Put any decorator on top of @store.wrap, even one that uses functools.wraps and keeps __wrapped__ pointing at the wrapped function, and is_wrapped returns False. The boot validator then rejects the platform, because it advertises idempotency.supported=True but appears to have no wrapped method. The validator runs in create_adcp_server_from_platform (decisioning/serve.py:475-479), and again per request for scoped capabilities in PlatformHandler.get_adcp_capabilities (decisioning/handler.py:1886-1894).

Reproduction (adcp 8.0.0)

import functools
from types import SimpleNamespace

from adcp.decisioning.validate_idempotency import validate_idempotency_wiring
from adcp.server.idempotency import IdempotencyStore, MemoryBackend, is_wrapped

store = IdempotencyStore(backend=MemoryBackend())


def translate_errors(fn):
    @functools.wraps(fn)
    async def outer(*args, **kwargs):
        return await fn(*args, **kwargs)
    return outer


class Seller:
    capabilities = SimpleNamespace(adcp=SimpleNamespace(idempotency=SimpleNamespace(supported=True)))

    @translate_errors
    @store.wrap
    async def create_media_buy(self, params, context=None):
        return {"media_buy_id": "mb_1"}


seller = Seller()
print("is_wrapped(outer):", is_wrapped(seller.create_media_buy))
print("is_wrapped(outer.__wrapped__):", is_wrapped(seller.create_media_buy.__wrapped__))
try:
    validate_idempotency_wiring(seller)
    print("validator: ok")
except Exception as exc:
    print("validator:", type(exc).__name__, exc.code, "|", str(exc)[:90])
is_wrapped(outer): False
is_wrapped(outer.__wrapped__): True
validator: AdcpError INVALID_REQUEST | AdcpError[INVALID_REQUEST / terminal]: capabilities.adcp.idempotency.supported=True is dec

The comment at store.py:367-373 explains why the check doesn't call inspect.unwrap(): that returns the innermost handler, which is not in the set. That reasoning holds for unwrap-then-check. It does not rule out checking each link of the __wrapped__ chain.

Why an adopter hits this

Outer decorators on handlers are common: error translation, metrics, tracing, auth. Embedded Sales Agent wraps every idempotent method in translate_idempotency_conflict (core/idempotency.py), which maps IdempotencyConflictError to a wire IDEMPOTENCY_CONFLICT with recovery="correctable". Without a workaround, the platform fails boot validation.

ESA's workaround imports the private registry and adds its outer function to it (_WRAPPED_FUNCTIONS.add(_wrapper), core/idempotency.py ~line 112). It guards the import with except (ImportError, AttributeError) in case the SDK renames it. The other option, _adcp_idempotency_external = True, turns the check off for the whole platform, which defeats its purpose.

Ask

Either option keeps the existing spoof resistance, because membership is still granted only by IdempotencyStore.wrap:

  1. Have is_wrapped walk the __wrapped__ chain with a bounded depth, and return True if any link is in _WRAPPED_FUNCTIONS.
  2. Add a public mark_wrapped(outer, inner) (or IdempotencyStore.register_outer(outer, inner)) that registers outer only if inner is already registered.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): middleware (label not found in repo — flagged in run summary)
    Status: ready-to-implement
    Milestone: (omitted — no version target named)

    What the experts said:

    • code-reviewer: Fix is correct and non-breaking; missing test for @outer @store.wrap scenario is a blocker that must ship with the fix; docstring needs functools.wraps contract note; update the store.py:367–373 comment to describe the per-step chain-walk vs. inspect.unwrap().
    • security-reviewer: Safe to ship. _WRAPPED_FUNCTIONS is still only written by IdempotencyStore.wrap — the chain-walk changes what is_wrapped accepts as evidence, not what gets registered. Spoof via manual __wrapped__ assignment is no worse than the existing _adcp_idempotency_external escape hatch. Update the maintainer comment at store.py:367–373 so it doesn't mislead future maintainers into reverting the fix.

    My take: The root cause is clear and both experts converge on Option 1 (walk the __wrapped__ chain, check each link). Option 2 (mark_wrapped public API) has the same spoofing surface with worse adopter ergonomics, and the existing _adcp_idempotency_external escape hatch already covers fully external dedup. This is a non-breaking bug fix that should land before ESA's private-registry workaround spreads further.

    Implementation scope:

    • src/adcp/server/idempotency/store.py — is_wrapped() (lines 89–99): Replace the direct membership check with a bounded __wrapped__ chain-walk (depth cap of ~16 to guard against pathological cycles). Check each link; return True as soon as any link is in _WRAPPED_FUNCTIONS. __func__ resolution applies only to the outermost call (mid-chain links are always raw functions via functools.wraps). Add a # guard against pathological __wrapped__ cycles comment on the depth cap.
    • src/adcp/server/idempotency/store.py — comment block at lines 367–373: Replace the "Do NOT change to inspect.unwrap()-then-check" language with a note explaining that per-step chain-walk is the correct idiom and why it differs from full unwrapping (full unwrap reaches the original handler, which is not in the set).
    • src/adcp/server/idempotency/store.py — is_wrapped() docstring: Add a line stating that outer decorators must use functools.wraps (or otherwise set __wrapped__) for the chain-walk to reach the registered wrapper. An outer decorator that omits functools.wraps will still fail validation — this is expected and should be mentioned in the error message path.
    • tests/test_validate_idempotency_wiring.py — TestIsWrapped: Add a test: apply a @functools.wraps-using outer decorator on top of @store.wrap and assert is_wrapped(outer) returns True. Also assert the two-deep case (@outer1 @outer2 @store.wrap) works. Verify is_wrapped still returns False for an outer decorator that does NOT use functools.wraps.
    • Required checks before PR: pytest tests/test_validate_idempotency_wiring.py, mypy src/adcp/server/idempotency/, ruff check ..
    • Non-breaking rationale: is_wrapped only gains True returns where it previously returned False (false negatives). No public API signature changes. Existing wrapped functions are found on the first iteration with no behavior change.

    Triaged by Claude Code. Session: https://claude.ai/code/session_01MFKwWqzacWU1RJCGobp5GT


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions