Skip to content

bug(reporting): Core-only capability block advertises tier endpoints and doorbells by default #1180

Closed

Description

@bokelley

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 when reconciled_billing is true". It is unconditionally present regardless of the tier flag, which on this same model defaults to False.
  • 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 to None) so a Core-only block can omit them, and so presence carries information.
  • Validate tier consistency: receipt_task present requires reconciled_billing: true; readiness_notification present requires managed_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_notification cannot be emitted when managed_delivery is false or absent.
  • receipt_task cannot be emitted when reconciled_billing is false or absent.
  • status_notification and ledger_notification are 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

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

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (confirmed — source verified against the filed description)
    Bucket(s): client, validation
    Status: ready-for-human
    Milestone: omitted

    What the experts said:

    • ad-tech-protocol-expert: Bug is real and material — readiness_notification defaults to 'reporting.delivery_ready' while managed_delivery defaults to False, making every Core-only instantiation a normative-MUST-OMIT violation; receipt_task is equally wrong; status_notification/ledger_notification are 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.
    • code-reviewer: Correct fix path is schema→codegen, not a direct edit to generated_poc/ (wiped on every regen); a _forward_compat.py patch is technically feasible but must also set default = None on the copied FieldInfo (existing _patch_model_field only replaces the annotation); tier-consistency model_validator cannot be added post-hoc via model_rebuild — it needs to live at the aliases.py/wrapper layer; human must make the call on semver consequence and protocol-level semantics.

    My take: The readiness_notification default is an unambiguous spec violation ("Core sellers MUST omit it" in the field description), and receipt_task being non-None when reconciled_billing: False is internally contradictory. Fixing these changes field defaults from non-None strings to None, 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.py patch is the right interim path, and (c) what semver track this ships on.

    Implementation brief (for human to authorize):

    • The two urgent fields are readiness_notification (MUST omit for Core sellers, line 78-83) and receipt_task (must require reconciled_billing: true, lines 72-77). status_notification / ledger_notification (lines 84-95) are tier-independent and lower priority.
    • Preferred path: fix the upstream JSON schema at core/reporting_delivery_capabilities.json, regen via datamodel-code-generator, verify aliases/forward-compat layer still resolves correctly.
    • Interim path if schema is not quickly accessible: add a _forward_compat.py patcher that sets annotation = Literal['...'] | None and default = None on the affected FieldInfo objects; tier-consistency validator must live in a wrapper class at the aliases.py layer (Pydantic does not support post-hoc model_validator injection via model_rebuild).
    • Required tests: all six acceptance criteria from the issue; confirm claude-triaged PR gate passes.
    • Related open issues feat(reporting): complete seller-side Managed Delivery and Reconciled Billing #1167 (seller-side MD/RB vertical slice) and feat(reporting): add a transactional notification outbox and account activity projection #1168 (notification outbox) overlap in file scope — coordinate before the schema regen to avoid a double-churn codegen diff.

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


    Generated by Claude Code

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