Repository navigation
Description
Summary
On 8.0.0, ReliableReportingService raises plain Python exceptions from its buyer-facing methods:
ReliableReportingUnavailableError(RuntimeError)(adcp/reporting/service_lifecycle.py:42-45)ReliableReportingConfigurationError(ValueError)(adcp/reporting/service.py:95-96)LedgerConflictError(RuntimeError), which carries a.code(adcp/reporting/ledger/store.py:107-117)
When the service is mounted on a DecisioningPlatform with install(), the ReportingInstallMixin methods (service.py:1269-1291) call the service without translating these. The dispatcher then wraps them as INTERNAL_ERROR with recovery="terminal" (adcp/decisioning/dispatch.py:1647-1671). A buyer told "terminal" stops retrying, even when the cause is a restart (SERVICE_UNAVAILABLE, transient) or its own bad cursor (correctable).
The managed-production composition already does this mapping. ReportingProductionHandler turns LedgerConflictError into ADCPTaskError(code=error.code) for sync_accounts, sync_reporting_status and get_media_buy_delivery (adcp/reporting/production/handler.py:256-265, 286-290, 411-417). The Core path has no equivalent.
Reproduction (adcp 8.0.0)
import asyncio
import logging
import warnings
warnings.simplefilter("ignore")
logging.disable(logging.CRITICAL)
from adcp.decisioning import DecisioningCapabilities, DecisioningPlatform, SingletonAccounts
from adcp.decisioning.serve import create_adcp_server_from_platform
from adcp.reporting import ReliableReportingService
from adcp.reporting.ledger.store import encode_cursor
from adcp.server.auth import current_principal
from adcp.server.base import ToolContext
from adcp.types import GetMediaBuyDeliveryRequest, GetReportingStatusRequest
class Seller(DecisioningPlatform):
capabilities = DecisioningCapabilities(specialisms=["sales-non-guaranteed"], supported_billing=["operator"])
accounts = SingletonAccounts(account_id="acct")
def get_products(self, req, ctx): return {"products": []}
def create_media_buy(self, req, ctx): raise NotImplementedError
def update_media_buy(self, media_buy_id, patch, ctx): raise NotImplementedError
def sync_creatives(self, req, ctx): raise NotImplementedError
def get_media_buy_delivery(self, req, ctx): raise NotImplementedError
service = ReliableReportingService.memory(account_context=lambda c: None)
handler, _, _ = create_adcp_server_from_platform(service.install(Seller()))
async def show(label, call):
try:
await call
except Exception as exc:
print(f"{label}: {exc.code} / {exc.recovery} / caused_by={type(exc.__cause__).__name__}")
async def main():
status = GetReportingStatusRequest.model_validate({"account": {"account_id": "acct"}, "view": "summary"})
await show("not started", handler.get_reporting_status(status, ToolContext()))
await service.start()
# No authenticated principal -> default caller resolution refuses.
await show("no caller ", handler.get_reporting_status(status, ToolContext()))
# Authenticated exact revision read with a cursor minted for another revision.
current_principal.set("buyer-1")
delivery = GetMediaBuyDeliveryRequest.model_validate({
"account": {"account_id": "acct"},
"reporting_revision_id": "rev_a",
"pagination": {"cursor": encode_cursor({"revision": "rev_b"})},
})
await show("bad cursor ", handler.get_media_buy_delivery(delivery, ToolContext()))
await service.close()
asyncio.run(main())Output:
not started: INTERNAL_ERROR / terminal / caused_by=ReliableReportingUnavailableError
no caller : INTERNAL_ERROR / terminal / caused_by=ReliableReportingConfigurationError
bad cursor : INTERNAL_ERROR / terminal / caused_by=LedgerConflictError
Why an adopter hits this
Embedded Sales Agent mounts the service on its LazyPlatformRouter with install(). It subclasses the service (SalesagentReportingService in core/reporting.py) only to wrap get_reporting_status, sync_reporting_status and get_revision_content in _serve. _serve maps unavailable to SERVICE_UNAVAILABLE/transient, LedgerConflictError to its own code/correctable, and configuration errors to INVALID_REQUEST. That is about 40 LOC. Without it, every reporting call made while the service starts, restarts or fails tells the buyer to give up.
Ask
Translate in the SDK, so every composition gets the same wire errors:
- In the
install()mixin (or the service's public methods), mapReliableReportingUnavailableErrortoAdcpError("SERVICE_UNAVAILABLE", recovery="transient")andLedgerConflictErrortoAdcpError(error.code, recovery="correctable"), matchingReportingProductionHandler. - Split
ReliableReportingConfigurationErrorinto request-time refusals, which are buyer-visible (AUTH_REQUIRED/INVALID_REQUEST), and composition errors, which stayINTERNAL_ERROR. Today one class covers both a missing caller and a misconfigured service.
Activity
bokelley commentedon Oct 2, 2026
Triage
Classification: Bug
Bucket(s): handlers (label gap —
handlerslabel does not exist in this repo)Status: ready-to-implement
Milestone: (omitted — no target version named)
What the experts said:
ReportingInstallMixinmethods mirrors whatReportingProductionHandleralready does; non-breaking because adopters never call these methods directly (the dispatcher does), and the wire-level change fromINTERNAL_ERROR/terminaltoSERVICE_UNAVAILABLE/transientis the correct behavior.kindattribute toReliableReportingConfigurationErroris the clean way to split the two cases without widening the public API surface.My take: The bug is clear and well-characterized — three exception types escape the
ReportingInstallMixinwithout translation, producingINTERNAL_ERROR/terminalwhere buyers should get a recoverable error. The production handler already contains the correct mapping; this PR brings the Core path into alignment.Implementation scope:
src/adcp/reporting/service.py— addkind: Literal["misconfiguration", "caller_unavailable"] = "misconfiguration"toReliableReportingConfigurationError(line ~95); update the two runtime raise sites (lines ~1074 and ~1091 in_sync_reporting_status/_sync_reporting_receipts) to passkind="caller_unavailable"; wrap each of the fourReportingInstallMixinmethods (lines 1269–1291) with:await service.<method>(...)branch insync_reporting_statusandsync_reporting_receipts— leave thesuper()fallback paths unaffected.service_lifecycle.py,ledger/store.py,production/handler.py, ordispatch.py.install(): unavailable →SERVICE_UNAVAILABLE/transient, ledger conflict →error.code/correctable, caller-unavailable configuration error →SERVICE_UNAVAILABLE/transient, and misconfiguration-kind still →INTERNAL_ERROR/terminal. The issue's reproduction script is a ready-made basis. Zero existing test coverage forReportingInstallMixinexists, so this adds a new test file or extendstests/reporting/.pyteston reporting subset,mypy src/,ruff check ./black --check .ReliableReportingConfigurationError.kindis a new attribute with a default; all existingisinstancechecks and theconfiguration_error=ReliableReportingConfigurationErrorreference in_compose_productionare unaffected.Triaged by Claude Code. Session: https://claude.ai/code/session_014bgQL6e8jr5wcfoPhTER7b
Generated by Claude Code