Skip to content

fix(errors): align standard recovery defaults with published metadata #1151

Closed

Description

@bokelley

adcp==8.0.0b14 emits enum-valid but incorrect recovery classifications for 84 of the 119 published standard error codes in the immutable AdCP 3.2.0-rc.1 artifact.

Reproduction:

from adcp.server.helpers import adcp_error
print(adcp_error('AUTH_MISSING', 'Fixture'))
print(adcp_error('CREATIVE_SIZE_MISMATCH', 'Fixture'))

Both emit recovery: terminal; enums/error-code.json.enumMetadata classifies both as correctable. Schema-only validation accepts these values, so this requires a semantic assertion too. An incorrect terminal classification can cause a buyer to stop instead of correcting the request.

The cross-language harness in adcp#7447 exercises every published default through adcp_error → typed ADCPTaskError → create_mcp_server → a real in-memory MCP client. The incorrect values survive to structuredContent.adcp_error. All three explicit extension-code recovery overrides pass.

Please source standard-code defaults from the pinned published metadata (rather than an incomplete handwritten table), preserve valid explicit override behavior, and add exhaustive default-classification tests. The harness records the current findings without treating them as a conformance pass. This is distinct from the negotiated purchase coordinator in #1146 and reverse facade in #1147.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 13, 2026
  2. bokelley commented on Sep 13, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): handlers (adcp.server.helpers) — no matching label exists in this repo for handlers or validation (gap noted)
    Status: ready-to-implement
    Milestone: omitted (no version target named)

    What the experts said:

    • code-reviewer: confirmed 7 divergences (4 from report + IDEMPOTENCY_CONFLICT, IDEMPOTENCY_EXPIRED, UNSUPPORTED_FEATURE) plus IDEMPOTENCY_IN_FLIGHT missing entirely; hardcoded table is the root cause; replace with enumMetadata loader — no ambiguity, all 3 blockers are well-scoped
    • ad-tech-protocol-expert: enumMetadata.$comment contains a normative MUST directive ("SDKs MUST consume this block instead of parsing Recovery from prose"); mismatches are spec violations, not SDK discretion; schema-load approach is correct; recommends keeping SDK-extension codes in a separate _SDK_EXTENSION_CODES constant merged after load

    My take: Both experts converge with no disagreement. The fix is non-breaking — callers who pass recovery= explicitly are unaffected, and all defaults that change are currently wrong per spec. The risk of not fixing is agent buyers hard-stopping on AUTHORIZATION_REQUIRED (which is correctable), or looping forever on BUDGET_EXHAUSTED (which is terminal).

    Implementation scope:

    • src/adcp/server/helpers.py: Replace the hand-maintained STANDARD_ERROR_CODES dict (lines 29–98) with a _build_standard_error_codes() loader that reads enumMetadata from schemas/cache/3.2.0-rc.1/enums/error-code.json at import time (fall back to the bundled src/adcp/_schemas/3.2.0-rc.1/enums/error-code.json when available). Merge SDK-only extensions (NOT_SUPPORTED etc.) in a separate _SDK_EXTENSION_CODES constant after the spec load. Remove the stale comment on lines 84–95 asserting IDEMPOTENCY_CONFLICT/IDEMPOTENCY_EXPIRED are terminal "from a retry standpoint" — it contradicts enumMetadata.

    • tests/test_server_helpers.py: Add parametrized @pytest.mark.parametrize tests loading enumMetadata from the same JSON and asserting adcp_error(code, "x")["recovery"] == enumMetadata[code]["recovery"] for every spec code. This exhaustively covers all ~119 published codes and locks future schema-load correctness. Replace the current test_all_standard_codes_have_recovery shape-only check with this semantic assertion.

    • Non-breaking rationale: Function signature unchanged. Only callers relying on default recovery (no recovery= kwarg) are affected, and only in the direction of becoming spec-correct. The derived frozensets TRANSIENT_CODES, CORRECTABLE_CODES, TERMINAL_CODES will update automatically from the rebuilt dict.

    • Checks required: pytest tests/test_server_helpers.py, ruff check src/adcp/server/helpers.py, mypy src/adcp/server/helpers.py (the loader returns a fully-typed dict so no type: ignore should be needed; use cast() at the JSON boundary if mypy's no-any-return fires).


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


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 13, 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