You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(errors): align standard recovery defaults with published metadata #1151
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.
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.
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).
Activity
bokelley commentedon Sep 13, 2026
Triage
Classification: Bug
Bucket(s): handlers (
adcp.server.helpers) — no matching label exists in this repo forhandlersorvalidation(gap noted)Status: ready-to-implement
Milestone: omitted (no version target named)
What the experts said:
IDEMPOTENCY_CONFLICT,IDEMPOTENCY_EXPIRED,UNSUPPORTED_FEATURE) plusIDEMPOTENCY_IN_FLIGHTmissing entirely; hardcoded table is the root cause; replace withenumMetadataloader — no ambiguity, all 3 blockers are well-scopedenumMetadata.$commentcontains 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_CODESconstant merged after loadMy 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 onAUTHORIZATION_REQUIRED(which is correctable), or looping forever onBUDGET_EXHAUSTED(which is terminal).Implementation scope:
src/adcp/server/helpers.py: Replace the hand-maintainedSTANDARD_ERROR_CODESdict (lines 29–98) with a_build_standard_error_codes()loader that readsenumMetadatafromschemas/cache/3.2.0-rc.1/enums/error-code.jsonat import time (fall back to the bundledsrc/adcp/_schemas/3.2.0-rc.1/enums/error-code.jsonwhen available). Merge SDK-only extensions (NOT_SUPPORTEDetc.) in a separate_SDK_EXTENSION_CODESconstant after the spec load. Remove the stale comment on lines 84–95 assertingIDEMPOTENCY_CONFLICT/IDEMPOTENCY_EXPIREDare terminal "from a retry standpoint" — it contradictsenumMetadata.tests/test_server_helpers.py: Add parametrized@pytest.mark.parametrizetests loadingenumMetadatafrom the same JSON and assertingadcp_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 currenttest_all_standard_codes_have_recoveryshape-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 frozensetsTRANSIENT_CODES,CORRECTABLE_CODES,TERMINAL_CODESwill 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 notype: ignoreshould be needed; usecast()at the JSON boundary if mypy'sno-any-returnfires).Triaged by Claude Code. Session: https://claude.ai/code/session_011PqmhaMv1Ck4T79hbgTbsJ
Generated by Claude Code
fix(errors): align recovery defaults with published metadata