Repository navigation
Description
Summary
In 8.0.0-beta.15, ReportingDeliveryCapabilities declares four optional tier-gated fields as non-optional Literal types with populated defaults. A Core-only seller that constructs and serializes the model therefore advertises endpoints and notifications it does not implement — including one the field's own description says it MUST omit.
Current behavior
adcp/types/generated_poc/core/reporting_delivery_capabilities.py:
receipt_task: Literal['sync_reporting_receipts'] = 'sync_reporting_receipts'
readiness_notification: Literal['reporting.delivery_ready'] = 'reporting.delivery_ready'
status_notification: Literal['reporting.status_changed'] = 'reporting.status_changed'
ledger_notification: Literal['reporting.ledger_changed'] = 'reporting.ledger_changed'None is | None, and every one carries a default. There is no way to construct the model without them.
This contradicts the descriptions attached to the same fields:
receipt_task— "Required whenreconciled_billingis true". It is unconditionally present regardless of the tier flag, which on this same model defaults toFalse.readiness_notification— "Optional managed-delivery-only positive-readiness doorbell. It names a materialization at a destination, so Core sellers MUST omit it." The generated model makes omission impossible.status_notification/ledger_notification— described as "Optional", emitted unconditionally.
So the default construction of this model is internally inconsistent: managed_delivery: False and reconciled_billing: False alongside a managed-delivery-only doorbell and a reconciled-billing-only receipt task.
Impact
A buyer reading the capability block cannot distinguish a seller that implements sync_reporting_receipts from one that merely serialized the defaults. The tier flags say Core; the task fields say otherwise. Since these fields name tasks a buyer is expected to call, the buyer can reasonably call an endpoint that does not exist.
Required behavior
- Make all four fields optional (
| None, defaulting toNone) so a Core-only block can omit them, and so presence carries information. - Validate tier consistency:
receipt_taskpresent requiresreconciled_billing: true;readiness_notificationpresent requiresmanaged_delivery: true. - Consider a constructor or helper that builds a tier-correct block from the flags, so sellers cannot assemble a contradictory one.
Acceptance criteria
- A Core-only capability block can be constructed and serialized with none of the four fields present.
-
readiness_notificationcannot be emitted whenmanaged_deliveryis false or absent. -
receipt_taskcannot be emitted whenreconciled_billingis false or absent. -
status_notificationandledger_notificationare opt-in and absent unless set. - Round-tripping a Core block adds no tier fields.
- A test asserts the default-constructed Core block contains no managed-delivery or reconciled-billing task names.
Adopter impact
Embedded Sales Agent currently carries a subclass whose only purpose is to pop these four keys during serialization, because emitting them would be a false capability claim. That subclass exists solely to prevent the SDK from advertising on our behalf. We would delete it.
Related: #1167 (seller-side Managed Delivery and Reconciled Billing), #1168 (notification outbox).
Activity
bokelley commentedon Sep 16, 2026
Triage
Classification: Bug (confirmed — source verified against the filed description)
Bucket(s): client, validation
Status: ready-for-human
Milestone: omitted
What the experts said:
readiness_notificationdefaults to'reporting.delivery_ready'whilemanaged_deliverydefaults toFalse, making every Core-only instantiation a normative-MUST-OMIT violation;receipt_taskis equally wrong;status_notification/ledger_notificationare tier-independent and less urgent (no MUST-OMIT clause); the default→None change plus the tier-consistency validator are an atomic, coupled fix, not two independent steps — and both cross the semver-major line.generated_poc/(wiped on every regen); a_forward_compat.pypatch is technically feasible but must also setdefault = Noneon the copiedFieldInfo(existing_patch_model_fieldonly replaces the annotation); tier-consistencymodel_validatorcannot be added post-hoc viamodel_rebuild— it needs to live at thealiases.py/wrapper layer; human must make the call on semver consequence and protocol-level semantics.My take: The
readiness_notificationdefault is an unambiguous spec violation ("Core sellers MUST omit it" in the field description), andreceipt_taskbeing non-None whenreconciled_billing: Falseis internally contradictory. Fixing these changes field defaults from non-None strings toNone, which is a breaking change per this repo's semver conventions and crosses an interop boundary where field presence is load-bearing for buyers. A maintainer needs to decide: (a) whether to fix the upstream JSON schema and regen, or (b) whether a_forward_compat.pypatch is the right interim path, and (c) what semver track this ships on.Implementation brief (for human to authorize):
readiness_notification(MUST omit for Core sellers, line 78-83) andreceipt_task(must requirereconciled_billing: true, lines 72-77).status_notification/ledger_notification(lines 84-95) are tier-independent and lower priority.core/reporting_delivery_capabilities.json, regen viadatamodel-code-generator, verify aliases/forward-compat layer still resolves correctly._forward_compat.pypatcher that setsannotation = Literal['...'] | Noneanddefault = Noneon the affectedFieldInfoobjects; tier-consistency validator must live in a wrapper class at thealiases.pylayer (Pydantic does not support post-hocmodel_validatorinjection viamodel_rebuild).claude-triagedPR gate passes.Triaged by Claude Code. Session: https://claude.ai/code/session_01PWCT4YWYyWs6L5Uq7HvPsH
Generated by Claude Code