Repository navigation
Description
Every AdCP response schema composes core/protocol-envelope.json at its root via allOf,
so status, task_id, message, context_id, replayed, timestamp,
push_notification_config, governance_context, context, payload and adcp_error are
part of every response's contract. In adcp==6.6.0, 19 of the 24 *SuccessResponse aliases
do not inherit ProtocolEnvelope, so those eleven fields are untyped on them: a server that
sets one gets a pydantic extra, and a client that reads one gets an AttributeError.
Related to #822, which is a different bug in the same file (a stripped import producing
NameError). This one is about which classes get the base at all.
Measured against the shipped wheel
from adcp.types import ProtocolEnvelope
import adcp.types.aliases as A
for n in sorted(n for n in dir(A) if n.endswith("SuccessResponse") and not n.startswith("_")):
c = getattr(A, n)
if isinstance(c, type):
print(f"{'inherits' if issubclass(c, ProtocolEnvelope) else 'MISSING '} {n}")MISSING ActivateSignalSuccessResponse
MISSING BuildCreativeSuccessResponse
MISSING CalibrateContentSuccessResponse
inherits CreateContentStandardsSuccessResponse
MISSING CreateMediaBuySuccessResponse
MISSING GetAccountFinancialsSuccessResponse
MISSING GetBrandIdentitySuccessResponse
MISSING GetContentStandardsSuccessResponse
MISSING GetCreativeFeaturesSuccessResponse
MISSING GetMediaBuyArtifactsSuccessResponse
inherits GetProductsSuccessResponse
MISSING GetRightsSuccessResponse
inherits GetSignalsSuccessResponse
inherits ListContentStandardsSuccessResponse
MISSING LogEventSuccessResponse
MISSING ProvidePerformanceFeedbackSuccessResponse
MISSING SyncAccountsSuccessResponse
MISSING SyncAudiencesSuccessResponse
MISSING SyncCatalogsSuccessResponse
MISSING SyncCreativesSuccessResponse
MISSING SyncEventSourcesSuccessResponse
inherits UpdateContentStandardsSuccessResponse
MISSING UpdateMediaBuySuccessResponse
MISSING ValidateContentDeliverySuccessResponse
19 missing, 5 present.
The two structurally identical inputs that generate differently
content-standards/update-content-standards-response.json and
media-buy/create-media-buy-response.json have the same shape where it matters: the root
composes ../core/version-envelope.json and ../core/protocol-envelope.json through
allOf, and neither one's Success branch references the protocol envelope itself.
update-content-standards-response.json
root allOf: ['../core/version-envelope.json', '../core/protocol-envelope.json']
branch UpdateContentStandardsSuccess allOf: [] -> generated class INHERITS ProtocolEnvelope
create-media-buy-response.json
root allOf: ['../core/version-envelope.json', '../core/protocol-envelope.json']
branch CreateMediaBuySuccess allOf: [...] -> generated class does NOT
The branch-level difference runs the wrong way: CreateMediaBuySuccess carries more
composition than UpdateContentStandardsSuccess and gets less inheritance. So the
divergence is in codegen, not in the schemas.
The general rule the data fits: where a response schema has no oneOf, the alias resolves
to the root class and picks the base up from the root allOf; where it has oneOf, the
per-branch classes are generated without the root composition. UpdateContentStandards is
the one case that escapes it, which is what makes this look like a bug rather than a
deliberate exclusion.
Impact
Any field of the protocol envelope is untyped on those 19. Concretely, on the seller side:
status— the pinned envelope marks it required on every task response, so a seller that
cannot set it typed has to declare the field itself.replayed— AdCPL1/security.mdxidempotency rule 4 puts this on the response envelope
of a replayed request. A boundary that setsresponse.replayed = Truewrites an extra on
19 of 24 response types and a real field on 5, which is not a difference a caller can see.
Workaround in use
Naming ProtocolEnvelope as a second base on the local subclass:
class SyncCreativesResponse(LibrarySyncCreativesSuccess, ProtocolEnvelope):
...That is additive today and becomes a no-op when the generated class carries the base, so it
deletes cleanly. Filing so it can be deleted rather than kept.
Suggested fix
Attach ProtocolEnvelope to every generated oneOf branch class of a response whose root
composes core/protocol-envelope.json, not only to the branch the driver currently treats
specially. The check is on the ROOT schema's allOf, so it needs no per-branch table.
Activity
bokelley commentedon Sep 6, 2026
Triage
Classification: Bug
Bucket(s): codegen (no matching repo label; gap noted)
Status: ready-to-implement
Milestone: omitted
What the experts said:
emit_response_class()line 4136 inscripts/post_generate_fixes.py; MRO risk is low; existing branch-levelstatus: Literal[…]overrides survive the new base; requiresissubclass(XSuccessResponse, ProtocolEnvelope)test as merge gateProtocolEnvelopebase is a genuine conformance violation (idempotency rule 4 onreplayed;statusuntyped on 19 of 24 shapes); scope extends to ErrorResponse arms too (≈44 branch classes total, not just 24 SuccessResponse aliases); fix is additive and non-breakingMy take: The root cause is a single predicate in
scripts/post_generate_fixes.py:4133–4138—ProtocolEnvelopeis added only whenstatus.const == "submitted"ANDtask_idis present; all other arms fall through toAdcpVersionEnvelopealone. Fixing that predicate is non-breaking and makes the Python type surface match the wire contract.Implementation scope:
Primary fix: In
render()(which has access toself.root_schema), detect whether the root schema'sallOfcontains a$reftocore/protocol-envelope.jsonusing the existing_resolve_schema_refhelper. Pass aroot_composes_envelope: boolflag intoemit_response_class(). Updatebasesto always includeProtocolEnvelopewhen that flag is true (the currentis_submittedpath becomes a subset). Setself.needs_protocol_envelope = Trueon the flag path, not only theis_submittedpath.Scope: All 22 response files in
response_specswhose rootallOfincludesprotocol-envelope.json— affects*Response1(success) and*Response2(error) arms, ≈44 branch classes. ErrorResponse arms already declarestatus: Literal['rejected']in their body, so adding the base does not produce a wrong default.Required tests:
tests/test_code_generation.py: feedrewrite_response_arms_from_schemaa mock schema withallOf: [{$ref: …/core/protocol-envelope.json}]plus aoneOf; assert every emitted branch class hasProtocolEnvelopein its bases.*SuccessResponsename fromadcp.typesand assertissubclass(cls, ProtocolEnvelope).Post-fix: Run
python scripts/generate_types.pyfrom clean state; verify all 24*SuccessResponsealiases pass theissubclasscheck.Non-breaking rationale: Additive base class addition;
isinstance(response, ProtocolEnvelope)flips fromFalsetoTruefor 19 aliases, which is the correct behavior. The existing workaround (class SyncCreativesResponse(LibrarySyncCreativesSuccess, ProtocolEnvelope)) becomes a no-op and can be deleted after.Related: chore(codegen): post_generate_fixes.py drops ProtocolEnvelope import + aliases.py has stale defensive lookups #822 (closed) fixed the stripped import and stale lookups; this issue is about which classes receive the base in the first place.
Triaged by Claude Code. Session: https://claude.ai/code/session_0154kAxY2mafwL6zkkpdMZaj
Generated by Claude Code
KonstantinMirin commentedon Sep 8, 2026
The ERROR branches lose it too, and that is what forces a local wrapper
The listing above covers
*SuccessResponse. Measured on the same wheel (adcp==6.6.0), thenon-success branches of the same
oneOfare affected in the same way, and the three branchesof one response therefore end up with no common ancestor below
AdcpVersionEnvelope:create-media-buy-response.jsoncomposes both envelopes at its ROOT:A root
allOfapplies to the whole document, so every branch carriesProtocolEnvelopeandstatuson an error response is schema-valid.CreateMediaBuyResponse2not having it is thesame codegen defect this issue reports, one branch over.
Why this costs a consumer more than the missing fields
CreateMediaBuyResponseis generated as a bare union alias, which is the correct rendering ofa non-discriminated
oneOf— but a union alias istypes.UnionType, not atype. A servercannot name it as a return annotation and cannot
issubclassit, so anything that resolves aresponse type by annotation (a replay cache, a serializer registry, a transport boundary) gets
nothing back. Combined with the branches having no shared base, a consumer is pushed into one
of two workarounds, and this seller has both in tree today:
serialization — which then has to re-project every envelope field the wrapper owns, and
silently drops any it forgets;
The ask
Emitting a generated root class per
oneOfthat the branches inherit — carrying the rootallOfbases — resolves both halves at once: the fields come back, and consumers get a typethey can annotate and subclass instead of inventing one. That is strictly more than applying
the bases to each branch independently, which fixes the fields but leaves the union
un-nameable.
Measured while implementing the
adcp_versionresponse echo thatcompliance/universal/version-negotiation.yamlgrades; the two wrapper-shaped tools were theonly two of fourteen that could not carry the field.
bokelley commentedon Sep 8, 2026
Triage update (re-run on new comment)
Classification: Bug
Bucket(s): codegen (no matching repo label; gap noted in prior run)
Status: ready-to-implement (no change)
What the experts said on the new dimensions raised by @KonstantinMirin:
types.UnionType) is a Python type-system concern, not a wire-conformance issue — the AdCP spec governs wire shape (JSON schema), not the SDK class hierarchy; replay-cache keying is derived fromidempotency_keyon the wire request, not from Python class identity; Path A is the conformance fix and Path B is additive ergonomicsemit_response_class(), zero new exported names, noaliases.pytouch; Path B requires a new non-colliding root class,__all__andaliases.pyupdates, and audit of_forward_compat.py/_ergonomic.pypatchers — disproportionate for this issue's scopeMy take: The error-branch miss was already in the prior brief's scope (≈44 branch classes, not just 24 SuccessResponse aliases); that scope and implementation plan stand unchanged. The root-class proposal resolves a real ergonomic gap but is a distinct change — the SDK does not currently dispatch on
CreateMediaBuyResponseas a type annotation, so the union alias unnamability is not a conformance blocker today. Path A remains the right implementation; Path B should be filed as a follow-on if a type-dispatch registry materializes.ProtocolEnvelopeis on all branches.Triaged by Claude Code. Session: https://claude.ai/code/session_01AnGVLyg2y7TXFwiw1LBHBj
Generated by Claude Code
refactor: inherit the protocol envelope, delete the mixin that hand-d…
refactor: one A2A dispatch path, and message becomes a field the impl…
fix(codegen): inherit root allOf ProtocolEnvelope on every response arm
fix(codegen): inherit root allOf ProtocolEnvelope on every response arm
fix(codegen): inherit root allOf ProtocolEnvelope on every response a…
fix(types): restore the composed base dropped from the canonical clone
fix(types): restore the composed base dropped from the canonical clone (