Module adcp.reporting.production

Production reporting composition with explicit, frozen provider contracts.

Mount one support's handler, start its owned lifecycle, then activate accounts after migration and drain. The memory implementation is for conformance and does not claim durability. The PostgreSQL production store is adcp_reporting_storage.production.pg; both implement :class:~adcp.reporting.production.store.ReportingProductionStore.

Sub-modules

adcp.reporting.production.configuration

A typed admission boundary for the application's existing account task.

adcp.reporting.production.contracts

Provider declarations and trusted, immutable source generation bindings.

adcp.reporting.production.delivery_window

Immutable first-attempt deadlines for the three production delivery queues.

adcp.reporting.production.handler

Authenticated production routes with private, revision-bound exact reads.

adcp.reporting.production.memory

Reference production transactions for shared state-machine conformance.

adcp.reporting.production.notifications

Optional owned notification delivery, independent of complete polling.

adcp.reporting.production.offerings

Atomic offerings bind public promises to the actual producer and verifier.

adcp.reporting.production.service

One live SDK composition for admitted reporting work and truthful discovery.

adcp.reporting.production.source_registry

Fixed execution profiles and durable, secret-free service admission facts …

adcp.reporting.production.store

The store contract the production composition depends on …

Functions

def production_notification_workers(store: ReportingProductionStore,
projection: ReportingProductionProjection,
*,
subscriptions: ReportingSubscriptionResolver,
cipher: ReportingEnvelopeCipher,
signing: ReportingProductionSigning) ‑> tuple[ReportingNotificationWorker, ...]
Expand source code
def production_notification_workers(
    store: ReportingProductionStore,
    projection: ReportingProductionProjection,
    *,
    subscriptions: ReportingSubscriptionResolver,
    cipher: ReportingEnvelopeCipher,
    signing: ReportingProductionSigning,
) -> tuple[ReportingNotificationWorker, ...]:
    """Build all three real SDK queue workers for ``ReportingProductionSupport``.

    The support schedules these workers itself. Omitting them keeps polling
    and enabled atomic logical enqueue available, without advertising push.
    Retained epoch-zero readiness queues are never among these participants.
    """
    if (
        not isinstance(store, ReportingProductionStore)
        or projection.ledger is not store
        or not projection.policy["notifications_enabled"]
        or type(signing) is not ReportingProductionSigning
    ):
        raise ReportingNotificationError("notification_chain_unready")
    ReportingProductionSigning.__post_init__(signing)
    signed_subscriptions = _SignedSubscriptions(subscriptions)
    # The store builds its own exact queue classes; a subclass is refused there.
    outboxes = store.production_outboxes(projection)
    return tuple(
        ReportingNotificationWorker(
            outbox=outbox,
            subscriptions=signed_subscriptions,
            cipher=cipher,
            signing=signing,
            activity=outbox,
            clock=store.clock,
            delivery_window=ProductionDeliveryWindow(store, queue),
        )
        for outbox, queue in zip(outboxes, ("core", "status", "ready"))
    )

Build all three real SDK queue workers for ReportingProductionSupport.

The support schedules these workers itself. Omitting them keeps polling and enabled atomic logical enqueue available, without advertising push. Retained epoch-zero readiness queues are never among these participants.

Classes

class InMemoryReportingProductionOutbox (store: InMemoryReportingProductionStore)
Expand source code
class InMemoryReportingProductionOutbox(InMemoryReportingOutbox):
    """The ordinary SDK expansion/delivery state machine, in a separate collection."""

    _store: InMemoryReportingProductionStore

    def __init__(self, store: InMemoryReportingProductionStore) -> None:
        if store._production_outbox is None:
            raise ReportingNotificationError("notifications_disabled")
        self._store = store

    @property
    def _state(self) -> NotificationState:
        assert self._store._production_outbox is not None
        return self._store._production_outbox

The ordinary SDK expansion/delivery state machine, in a separate collection.

Ancestors

Inherited members

class InMemoryReportingProductionStore (**kwargs: Any)
Expand source code
class InMemoryReportingProductionStore(InMemoryReportingProjectionStore):
    """Matches production atomicity and epochs, without claiming durable storage."""

    _materializer_writer_epoch = 2
    production_support: weakref.ReferenceType[ReportingProductionSupport] | None = None

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self._production_accounts: dict[str, _Admission] = {}
        self._production_delivery_windows: dict[
            tuple[str, str], tuple[str, str, datetime, datetime]
        ] = {}
        self._production_generations: dict[ReportingConfigurationGenerationKey, str] = {}
        self._production_source_bindings: dict[
            ReportingConfigurationGenerationKey, ReportingProductionSourceBinding
        ] = {}
        self._production_destination_bindings: dict[
            tuple[ReportingConfigurationGenerationKey, str], bytes
        ] = {}
        self._production_outbox = (
            NotificationState() if self._notification_state is not None else None
        )
        self._production_status_heads: dict[ReportingDeliveryPrincipal, int] = {}
        self._production_boundaries: list[ReportingMaterializerBoundary] = []
        self._production_closed: dict[ReportingConfigurationGenerationKey, datetime] = {}
        self._production_source_turns: dict[ReportingConfigurationGenerationKey, int] = {}
        self._production_source_work: dict[str, _SourceWork] = {}

    def _owner(self) -> ReportingProductionSupport:
        from adcp.reporting.production.service import production_owner

        return production_owner(self)

    # -- the production store contract (adcp.reporting.production.store) ------

    @property
    def durable(self) -> bool:
        return False

    @property
    def storage_identity(self) -> object:
        return self

    @property
    def storage_open(self) -> bool:
        return True

    def is_sdk_production_store(self) -> bool:
        return type(self) is InMemoryReportingProductionStore

    def status_projection(
        self,
        *,
        consumer_status_enabled: bool,
        escalation: ReportingDeliveryEscalation | None,
        revision_ownership: bool,
    ) -> InMemoryReportingStatusProjection:
        return InMemoryReportingStatusProjection(
            self,
            consumer_status_enabled=consumer_status_enabled,
            escalation=escalation,
            revision_ownership=revision_ownership,
        )

    def is_sdk_status_projection(self, projection: object) -> bool:
        return type(projection) is InMemoryReportingStatusProjection

    def projection_linked(self, projection: ReportingProductionProjection) -> bool:
        return (
            type(projection.outbox) is InMemoryReportingProjectionOutbox
            and projection.outbox._store is self
        )

    def production_outboxes(
        self, projection: ReportingProductionProjection
    ) -> tuple[Any, Any, Any]:
        if type(self) is not InMemoryReportingProductionStore:
            raise ReportingNotificationError("notification_chain_unready")
        return (
            InMemoryReportingOutbox(self),
            projection.outbox,
            InMemoryReportingProductionOutbox(self),
        )

    def notification_workers_linked(self, workers: Sequence[Any]) -> bool:
        expected = (
            InMemoryReportingOutbox,
            InMemoryReportingProjectionOutbox,
            InMemoryReportingProductionOutbox,
        )
        return (
            all(getattr(w.outbox, "_store", None) is self for w in workers)
            and tuple(type(w.outbox) for w in workers) == expected
        )

    async def validate_production_schema(
        self, *, notifications: bool, service_context: bool
    ) -> None:
        """Memory has no catalog; it never advertises durability either."""

    async def read_delivery_window(
        self, key: tuple[str, str], *, now: datetime
    ) -> tuple[SavedDeliveryWindow | None, datetime]:
        async with self._lock:
            return self._production_delivery_windows.get(key), now

    async def reserve_delivery_attempt(
        self,
        activity: ReportingActivityStore,
        lease: DeliveryLease,
        *,
        request: ActivityRequest,
        now: datetime,
        queue: str,
        expected: tuple[str, str],
        horizon_seconds: int,
    ) -> tuple[WebhookAttempt | None, datetime | None, bool]:
        from adcp.reporting.production.delivery_window import inspect_window

        binding = lease.delivery.binding
        key = (binding.account_id, binding.idempotency_key)
        if not isinstance(activity, InMemoryReportingOutbox) or activity._store is not self:
            raise ReportingNotificationError("notification_retry_unready")
        async with self._mutation():
            saved = self._production_delivery_windows.get(key)
            deadline, expired = inspect_window(saved, expected, now)
            if expired:
                return None, deadline, True
            attempt = activity._reserve_attempt_locked(lease, request=request, now=now)
            if attempt is None:
                return None, deadline, False
            retained = self._production_delivery_windows.setdefault(
                key,
                (
                    *expected,
                    attempt.fired_at,
                    attempt.fired_at + timedelta(seconds=horizon_seconds),
                ),
            )
            return attempt, retained[3], False

    def maintenance_operations(self) -> tuple[MaintenanceOperation, ...]:
        return ()

    async def admit_production_configuration(
        self,
        configuration: ReportingConfiguration,
        binding: ReportingDestinationBinding,
        *,
        offering_id: str,
        service_context: ReportingProductionSourceContext | None = None,
    ) -> None:
        offering = self._owner()._configuration_offering(
            configuration, binding, offering_id=offering_id
        )
        async with self._mutation():
            await self.put_configuration(configuration)
            await self.put_destination_binding(binding)
            self._enroll(
                configuration, offering._producer_key, binding, service_context=service_context
            )

    def _enroll(
        self,
        configuration: ReportingConfiguration,
        producer_key: str,
        destination: ReportingDestinationBinding,
        *,
        service_context: ReportingProductionSourceContext | None = None,
    ) -> None:
        previous_context = self._production_source_bindings.get(configuration.generation_key)
        binding = self._owner()._source_binding(
            configuration,
            producer_key,
            service_context=service_context,
            document=previous_context.document() if previous_context is not None else None,
        )
        previous = self._production_generations.setdefault(
            configuration.generation_key, producer_key
        )
        previous_binding = self._production_source_bindings.setdefault(
            configuration.generation_key, binding
        )
        if previous != producer_key or previous_binding != binding:
            raise ReportingNotificationError("reporting_production_source_conflict")
        owner = self._owner()
        offering = owner._configuration_offering(
            configuration, destination, producer_key=producer_key
        )
        document = canonical_json_utf8_v1(owner._destination_binding(destination, offering).wire())
        original = self._production_destination_bindings.setdefault(
            (configuration.generation_key, destination.consumer_id), document
        )
        if original != document:
            raise ReportingNotificationError("reporting_production_destination_conflict")

    def _destination_document(self, binding: ReportingDestinationBinding) -> dict[str, Any] | None:
        raw = self._production_destination_bindings.get(
            (binding.generation_key, binding.consumer_id)
        )
        return dict(json.loads(raw)) if raw is not None else None

    def _configuration_lease_eligible(self, configuration: ReportingConfiguration) -> bool:
        if configuration.quarantined:
            return False
        try:
            self._check_source_generation(configuration)
        except Exception:
            return False
        return True

    def _check_source_generation(self, configuration: ReportingConfiguration) -> None:
        producer_key = self._production_generations.get(configuration.generation_key)
        binding = self._production_source_bindings.get(configuration.generation_key)
        if (
            configuration.account_id not in self._production_accounts
            or producer_key not in self._owner()._producer_keys()
            or binding is None
            or self._configurations.get(configuration.generation_key) != configuration
        ):
            raise LedgerConflictError("HISTORY_UNAVAILABLE", "producer generation is unavailable")
        self._owner()._check_source_binding(configuration, producer_key, binding.document())

    def _wake_obligation(self, account_id: str, obligation_id: str) -> None:
        super()._wake_obligation(account_id, obligation_id)
        obligation = self._obligations.get(obligation_id)
        if (
            obligation is not None
            and obligation.account_id == account_id
            and obligation.generation_key in self._production_generations
        ):
            previous = self._production_source_work.get(obligation_id)
            self._production_source_work[obligation_id] = _SourceWork(
                obligation, previous.turn if previous else 0
            )

    async def producer_closed_through(
        self, configuration: ReportingConfiguration
    ) -> datetime | None:
        async with self._lock:
            self._check_source_generation(configuration)
            return self._production_closed.get(configuration.generation_key)

    async def producer_constituents(
        self, configuration: ReportingConfiguration, obligation: ReportingObligationRecord
    ) -> tuple[ReportingConstituent, ...]:
        async with self._lock:
            self._check_source_generation(configuration)
            if obligation.generation_key != configuration.generation_key or set(
                obligation.media_buy_ids
            ) != set(configuration.media_buy_ids):
                raise LedgerConflictError("HISTORY_UNAVAILABLE", "source denominator differs")
            return self._production_source_bindings[configuration.generation_key].constituents()

    async def commit_producer_period(
        self,
        configuration: ReportingConfiguration,
        obligation: ReportingObligationRecord,
        *,
        previous_end: datetime | None,
    ) -> ReportingObligationRecord:
        check_next_period(configuration, obligation, previous_end)
        async with self._mutation():
            self._check_source_generation(configuration)
            current = self._production_closed.get(configuration.generation_key)
            if current != previous_end and (current is None or current < obligation.period.end):
                raise LedgerConflictError("HISTORY_UNAVAILABLE", "producer progress changed")
            stored = await self.commit_obligation(obligation)
            self._production_source_work.setdefault(
                stored.reporting_obligation_id, _SourceWork(stored)
            )
            self._production_closed[configuration.generation_key] = max(
                obligation.period.end, current or obligation.period.end
            )
            return stored

    async def next_producer_obligations(
        self, configuration: ReportingConfiguration, *, now: datetime, limit: int
    ) -> tuple[str, ...]:
        if type(limit) is not int or not 1 <= limit <= 64:
            raise ValueError("production acquisition limit must be in 1..64")
        async with self._lock:
            self._check_source_generation(configuration)
            candidates = sorted(
                (work.turn, work.obligation.reporting_obligation_id)
                for work in self._production_source_work.values()
                if work.obligation.generation_key == configuration.generation_key
                and work.obligation.period.end <= now
                and work.state == "pending"
            )[:limit]
            turn = self._production_source_turns.get(configuration.generation_key, 0)
            for offset, (_, identifier) in enumerate(candidates, 1):
                work = self._production_source_work[identifier]
                self._production_source_work[identifier] = _SourceWork(
                    work.obligation, turn + offset
                )
            self._production_source_turns[configuration.generation_key] = turn + len(candidates)
            return tuple(identifier for _, identifier in candidates)

    async def finish_producer_acquisition(
        self, configuration: ReportingConfiguration, *, reporting_obligation_id: str
    ) -> None:
        async with self._lock:
            self._check_source_generation(configuration)
            work = self._production_source_work[reporting_obligation_id]
            if work.obligation.generation_key != configuration.generation_key:
                raise LedgerConflictError("HISTORY_UNAVAILABLE", "producer generation differs")
            revisions = await self.list_revisions(
                account_id=configuration.account_id,
                reporting_obligation_id=reporting_obligation_id,
            )
            self._production_source_work[reporting_obligation_id] = _SourceWork(
                work.obligation, work.turn, acquisition_state(work.obligation, revisions)
            )

    async def activate_production(self, *, account_id: str) -> bool:
        owner = self._owner()
        async with self._mutation():
            projection = self._projection_accounts.get(account_id)
            if (
                projection is None
                or not projection.ready
                or projection.policy != owner.projection.policy
            ):
                raise ReportingNotificationError("status_projection_activation_required")
            policy = owner._admission_policy()
            current = self._production_accounts.get(account_id)
            if current is not None:
                if current.policy != policy:
                    raise ReportingNotificationError("reporting_production_policy_conflict")
                return False
            self._production_accounts[account_id] = _Admission(self._clock(), policy)
            for _, _, record in self._retained_delivery_records():
                if (
                    isinstance(record, ReportingDestinationBinding)
                    and record.principal.account_id == account_id
                ):
                    configuration = self._configurations[record.generation_key]
                    try:
                        offering = owner._configuration_offering(configuration, record)
                    # Unsupported or unavailable bindings remain unadmitted.
                    except Exception:  # nosec B112
                        continue
                    self._enroll(configuration, offering._producer_key, record)
            return True

    def _check_admission(self, lease: ReportingMaterializerLease) -> None:
        if lease.admission_epoch != 2:
            return
        admission = self._production_accounts.get(lease.scope.principal.account_id)
        if admission is None or lease.attempt.created_at < admission.activated_at:
            raise failure("BINDING_MISMATCH")
        self._owner()._check_context(
            self._context(lease.scope),
            lease.request.verification_key,
            admission.policy,
            self._production_generations.get(lease.scope.generation_key),
            (
                self._production_source_bindings[lease.scope.generation_key].document()
                if lease.scope.generation_key in self._production_source_bindings
                else None
            ),
            self._destination_document(self._context(lease.scope).binding),
        )

    def _new_admission_epoch(
        self, context: MaterializerContext, key: ReportingVerificationKey
    ) -> int:
        admission = self._production_accounts.get(context.scope.principal.account_id)
        if admission is None:
            raise ReportingNotificationError("reporting_production_activation_required")
        self._owner()._check_context(
            context,
            key,
            admission.policy,
            self._production_generations.get(context.configuration.generation_key),
            (
                self._production_source_bindings[context.configuration.generation_key].document()
                if context.configuration.generation_key in self._production_source_bindings
                else None
            ),
            self._destination_document(context.binding),
        )
        return 2

    def _materializer_candidate_enabled(self, account_id: str) -> bool:
        return account_id in self._production_accounts

    def _held(self, lease: ReportingMaterializerLease) -> _Work | None:
        work = super()._held(lease)
        if work is not None:
            self._check_admission(lease)
        return work

    def _materializer_capture_collections(
        self, outcome: ReportingMaterializationRecord
    ) -> tuple[dict[ReportingDeliveryPrincipal, int], list[ReportingMaterializerBoundary]]:
        work = self._materializer_work.get(
            (
                outcome.scope.principal.account_id,
                outcome.scope.consumer_id,
                outcome.reporting_materialization_id,
            )
        )
        if work is not None and work.admission_epoch == 2:
            return self._production_status_heads, self._production_boundaries
        return super()._materializer_capture_collections(outcome)

    def _enqueue_materializer(
        self, event: ReportingDomainEvent, lease: ReportingMaterializerLease
    ) -> None:
        if lease.admission_epoch == 0:
            return super()._enqueue_materializer(event, lease)
        self._check_admission(lease)
        if self._production_outbox is None:
            raise failure("BINDING_MISMATCH")
        self._production_outbox.enqueue(event)
        if (
            self._production_outbox.events.get(
                (event.account_id, event.consumer_namespace, event.notification_id)
            )
            != event
        ):
            raise failure("BINDING_MISMATCH")

    async def read_production_boundaries(
        self, *, caller: ReportingDeliveryPrincipal, after: int = 0, limit: int = 100
    ) -> tuple[ReportingMaterializerBoundary, ...]:
        if type(after) is not int or after < 0 or type(limit) is not int or not 1 <= limit <= 100:
            raise ValueError("production boundary reads require bounded positions")
        async with self._lock:
            return tuple(
                b for b in self._production_boundaries if b.caller == caller and b.sequence > after
            )[:limit]

Matches production atomicity and epochs, without claiming durable storage.

Ancestors

Class variables

var production_support : weakref.ReferenceType[ReportingProductionSupport] | None

Instance variables

prop durable : bool
Expand source code
@property
def durable(self) -> bool:
    return False
prop storage_identity : object
Expand source code
@property
def storage_identity(self) -> object:
    return self
prop storage_open : bool
Expand source code
@property
def storage_open(self) -> bool:
    return True

Methods

async def activate_production(self, *, account_id: str) ‑> bool
Expand source code
async def activate_production(self, *, account_id: str) -> bool:
    owner = self._owner()
    async with self._mutation():
        projection = self._projection_accounts.get(account_id)
        if (
            projection is None
            or not projection.ready
            or projection.policy != owner.projection.policy
        ):
            raise ReportingNotificationError("status_projection_activation_required")
        policy = owner._admission_policy()
        current = self._production_accounts.get(account_id)
        if current is not None:
            if current.policy != policy:
                raise ReportingNotificationError("reporting_production_policy_conflict")
            return False
        self._production_accounts[account_id] = _Admission(self._clock(), policy)
        for _, _, record in self._retained_delivery_records():
            if (
                isinstance(record, ReportingDestinationBinding)
                and record.principal.account_id == account_id
            ):
                configuration = self._configurations[record.generation_key]
                try:
                    offering = owner._configuration_offering(configuration, record)
                # Unsupported or unavailable bindings remain unadmitted.
                except Exception:  # nosec B112
                    continue
                self._enroll(configuration, offering._producer_key, record)
        return True
async def admit_production_configuration(self,
configuration: ReportingConfiguration,
binding: ReportingDestinationBinding,
*,
offering_id: str,
service_context: ReportingProductionSourceContext | None = None) ‑> None
Expand source code
async def admit_production_configuration(
    self,
    configuration: ReportingConfiguration,
    binding: ReportingDestinationBinding,
    *,
    offering_id: str,
    service_context: ReportingProductionSourceContext | None = None,
) -> None:
    offering = self._owner()._configuration_offering(
        configuration, binding, offering_id=offering_id
    )
    async with self._mutation():
        await self.put_configuration(configuration)
        await self.put_destination_binding(binding)
        self._enroll(
            configuration, offering._producer_key, binding, service_context=service_context
        )
async def commit_producer_period(self,
configuration: ReportingConfiguration,
obligation: ReportingObligationRecord,
*,
previous_end: datetime | None) ‑> ReportingObligationRecord
Expand source code
async def commit_producer_period(
    self,
    configuration: ReportingConfiguration,
    obligation: ReportingObligationRecord,
    *,
    previous_end: datetime | None,
) -> ReportingObligationRecord:
    check_next_period(configuration, obligation, previous_end)
    async with self._mutation():
        self._check_source_generation(configuration)
        current = self._production_closed.get(configuration.generation_key)
        if current != previous_end and (current is None or current < obligation.period.end):
            raise LedgerConflictError("HISTORY_UNAVAILABLE", "producer progress changed")
        stored = await self.commit_obligation(obligation)
        self._production_source_work.setdefault(
            stored.reporting_obligation_id, _SourceWork(stored)
        )
        self._production_closed[configuration.generation_key] = max(
            obligation.period.end, current or obligation.period.end
        )
        return stored
async def finish_producer_acquisition(self, configuration: ReportingConfiguration, *, reporting_obligation_id: str) ‑> None
Expand source code
async def finish_producer_acquisition(
    self, configuration: ReportingConfiguration, *, reporting_obligation_id: str
) -> None:
    async with self._lock:
        self._check_source_generation(configuration)
        work = self._production_source_work[reporting_obligation_id]
        if work.obligation.generation_key != configuration.generation_key:
            raise LedgerConflictError("HISTORY_UNAVAILABLE", "producer generation differs")
        revisions = await self.list_revisions(
            account_id=configuration.account_id,
            reporting_obligation_id=reporting_obligation_id,
        )
        self._production_source_work[reporting_obligation_id] = _SourceWork(
            work.obligation, work.turn, acquisition_state(work.obligation, revisions)
        )
def is_sdk_production_store(self) ‑> bool
Expand source code
def is_sdk_production_store(self) -> bool:
    return type(self) is InMemoryReportingProductionStore
def is_sdk_status_projection(self, projection: object) ‑> bool
Expand source code
def is_sdk_status_projection(self, projection: object) -> bool:
    return type(projection) is InMemoryReportingStatusProjection
def maintenance_operations(self) ‑> tuple[tuple[str, Callable[[], Awaitable[typing.Any]]], ...]
Expand source code
def maintenance_operations(self) -> tuple[MaintenanceOperation, ...]:
    return ()
async def next_producer_obligations(self, configuration: ReportingConfiguration, *, now: datetime, limit: int) ‑> tuple[str, ...]
Expand source code
async def next_producer_obligations(
    self, configuration: ReportingConfiguration, *, now: datetime, limit: int
) -> tuple[str, ...]:
    if type(limit) is not int or not 1 <= limit <= 64:
        raise ValueError("production acquisition limit must be in 1..64")
    async with self._lock:
        self._check_source_generation(configuration)
        candidates = sorted(
            (work.turn, work.obligation.reporting_obligation_id)
            for work in self._production_source_work.values()
            if work.obligation.generation_key == configuration.generation_key
            and work.obligation.period.end <= now
            and work.state == "pending"
        )[:limit]
        turn = self._production_source_turns.get(configuration.generation_key, 0)
        for offset, (_, identifier) in enumerate(candidates, 1):
            work = self._production_source_work[identifier]
            self._production_source_work[identifier] = _SourceWork(
                work.obligation, turn + offset
            )
        self._production_source_turns[configuration.generation_key] = turn + len(candidates)
        return tuple(identifier for _, identifier in candidates)
def notification_workers_linked(self, workers: Sequence[Any]) ‑> bool
Expand source code
def notification_workers_linked(self, workers: Sequence[Any]) -> bool:
    expected = (
        InMemoryReportingOutbox,
        InMemoryReportingProjectionOutbox,
        InMemoryReportingProductionOutbox,
    )
    return (
        all(getattr(w.outbox, "_store", None) is self for w in workers)
        and tuple(type(w.outbox) for w in workers) == expected
    )
async def producer_closed_through(self, configuration: ReportingConfiguration) ‑> datetime.datetime | None
Expand source code
async def producer_closed_through(
    self, configuration: ReportingConfiguration
) -> datetime | None:
    async with self._lock:
        self._check_source_generation(configuration)
        return self._production_closed.get(configuration.generation_key)
async def producer_constituents(self,
configuration: ReportingConfiguration,
obligation: ReportingObligationRecord) ‑> tuple[ProductConstituentV1 | PackageItemConstituentV1 | MediaBuyConstituentV1, ...]
Expand source code
async def producer_constituents(
    self, configuration: ReportingConfiguration, obligation: ReportingObligationRecord
) -> tuple[ReportingConstituent, ...]:
    async with self._lock:
        self._check_source_generation(configuration)
        if obligation.generation_key != configuration.generation_key or set(
            obligation.media_buy_ids
        ) != set(configuration.media_buy_ids):
            raise LedgerConflictError("HISTORY_UNAVAILABLE", "source denominator differs")
        return self._production_source_bindings[configuration.generation_key].constituents()
def production_outboxes(self,
projection: ReportingProductionProjection) ‑> tuple[typing.Any, typing.Any, typing.Any]
Expand source code
def production_outboxes(
    self, projection: ReportingProductionProjection
) -> tuple[Any, Any, Any]:
    if type(self) is not InMemoryReportingProductionStore:
        raise ReportingNotificationError("notification_chain_unready")
    return (
        InMemoryReportingOutbox(self),
        projection.outbox,
        InMemoryReportingProductionOutbox(self),
    )
def projection_linked(self,
projection: ReportingProductionProjection) ‑> bool
Expand source code
def projection_linked(self, projection: ReportingProductionProjection) -> bool:
    return (
        type(projection.outbox) is InMemoryReportingProjectionOutbox
        and projection.outbox._store is self
    )
async def read_delivery_window(self, key: tuple[str, str], *, now: datetime) ‑> tuple[tuple[str, str, datetime.datetime, datetime.datetime] | None, datetime.datetime]
Expand source code
async def read_delivery_window(
    self, key: tuple[str, str], *, now: datetime
) -> tuple[SavedDeliveryWindow | None, datetime]:
    async with self._lock:
        return self._production_delivery_windows.get(key), now
async def read_production_boundaries(self, *, caller: ReportingDeliveryPrincipal, after: int = 0, limit: int = 100) ‑> tuple[ReportingMaterializerBoundary, ...]
Expand source code
async def read_production_boundaries(
    self, *, caller: ReportingDeliveryPrincipal, after: int = 0, limit: int = 100
) -> tuple[ReportingMaterializerBoundary, ...]:
    if type(after) is not int or after < 0 or type(limit) is not int or not 1 <= limit <= 100:
        raise ValueError("production boundary reads require bounded positions")
    async with self._lock:
        return tuple(
            b for b in self._production_boundaries if b.caller == caller and b.sequence > after
        )[:limit]
async def reserve_delivery_attempt(self,
activity: ReportingActivityStore,
lease: DeliveryLease,
*,
request: ActivityRequest,
now: datetime,
queue: str,
expected: tuple[str, str],
horizon_seconds: int) ‑> tuple[WebhookAttempt | None, datetime.datetime | None, bool]
Expand source code
async def reserve_delivery_attempt(
    self,
    activity: ReportingActivityStore,
    lease: DeliveryLease,
    *,
    request: ActivityRequest,
    now: datetime,
    queue: str,
    expected: tuple[str, str],
    horizon_seconds: int,
) -> tuple[WebhookAttempt | None, datetime | None, bool]:
    from adcp.reporting.production.delivery_window import inspect_window

    binding = lease.delivery.binding
    key = (binding.account_id, binding.idempotency_key)
    if not isinstance(activity, InMemoryReportingOutbox) or activity._store is not self:
        raise ReportingNotificationError("notification_retry_unready")
    async with self._mutation():
        saved = self._production_delivery_windows.get(key)
        deadline, expired = inspect_window(saved, expected, now)
        if expired:
            return None, deadline, True
        attempt = activity._reserve_attempt_locked(lease, request=request, now=now)
        if attempt is None:
            return None, deadline, False
        retained = self._production_delivery_windows.setdefault(
            key,
            (
                *expected,
                attempt.fired_at,
                attempt.fired_at + timedelta(seconds=horizon_seconds),
            ),
        )
        return attempt, retained[3], False
def status_projection(self,
*,
consumer_status_enabled: bool,
escalation: ReportingDeliveryEscalation | None,
revision_ownership: bool) ‑> InMemoryReportingStatusProjection
Expand source code
def status_projection(
    self,
    *,
    consumer_status_enabled: bool,
    escalation: ReportingDeliveryEscalation | None,
    revision_ownership: bool,
) -> InMemoryReportingStatusProjection:
    return InMemoryReportingStatusProjection(
        self,
        consumer_status_enabled=consumer_status_enabled,
        escalation=escalation,
        revision_ownership=revision_ownership,
    )
async def validate_production_schema(self, *, notifications: bool, service_context: bool) ‑> None
Expand source code
async def validate_production_schema(
    self, *, notifications: bool, service_context: bool
) -> None:
    """Memory has no catalog; it never advertises durability either."""

Memory has no catalog; it never advertises durability either.

Inherited members

class ReportingConfigurationAdmission (offering_id: str,
configuration: ReportingConfiguration,
binding: ReportingDestinationBinding,
*,
configuration_wire: Mapping[str, Any])
Expand source code
@dataclass(frozen=True)
class ReportingConfigurationAdmission:
    """Resolved by trusted account/provider code, never decoded from buyer JSON.

    The bound references are opaque; credentials stay in destination sessions.
    The SDK validates the complete frozen tuple before admitting configuration.
    """

    offering_id: str
    configuration: ReportingConfiguration
    binding: ReportingDestinationBinding
    configuration_wire: Mapping[str, Any] = field(kw_only=True, repr=False, compare=False)
    _wire: bytes = field(init=False, repr=False)

    def __post_init__(self) -> None:
        from adcp.validation.schema_loader import get_named_validator

        wire = canonical_json_utf8_v1(dict(self.configuration_wire))
        validator = get_named_validator("core/reporting-delivery-config.json")
        if validator is None or next(validator.iter_errors(json.loads(wire)), None) is not None:
            raise ValueError("configuration must satisfy the complete public contract")
        object.__setattr__(self, "_wire", wire)

    def wire(self) -> dict[str, Any]:
        return dict(json.loads(self._wire))

    def check(self, support: ReportingProductionSupport) -> None:
        from adcp.reporting.ledger.store import reject_reserved_authoritative_party

        config, binding, raw = self.configuration, self.binding, self.wire()
        reject_reserved_authoritative_party(config)
        if raw.get("authoritative_party", "seller") != "seller":
            raise LedgerConflictError("UNSUPPORTED_FEATURE", "consumer authority is reserved")
        offering = support._configuration_offering(config, binding, offering_id=self.offering_id)
        schedule = offering.configuration_schedule(config)
        supplied_schedule = dict(raw["schedule"])
        if "period_anchor" in supplied_schedule:
            supplied_schedule["period_anchor"] = aware_timestamp(
                supplied_schedule["period_anchor"]
            ).isoformat()
            schedule["period_anchor"] = aware_timestamp(schedule["period_anchor"]).isoformat()
        scope = raw["scope"]
        # This producer freezes an explicit full media-buy denominator. An
        # application's dynamic all-buy or partial-coverage implementation must
        # not be represented as this installed exact-generation contract.
        if (
            raw["delivery_config_id"] != config.delivery_config_id
            or raw["delivery_config_version"] != config.delivery_config_version
            or raw["offering_id"] != self.offering_id
            or raw["feed_purpose"] != config.feed_purpose
            or raw["report_definition_id"] != config.report_definition_id
            or raw["reporting_profile"] != config.reporting_profile
            or raw["required_finality"] != config.required_finality
            or raw["reconciliation_mode"] != binding.reconciliation_mode
            or set(scope) != {"media_buy_ids"}
            or set(scope["media_buy_ids"]) != set(config.media_buy_ids)
            or raw["coverage_requirement"] != "full"
            or supplied_schedule != schedule
            or raw.get("method") != support._destination_binding(binding, offering).wire()
            or raw["active"] != (config.activated_at is not None and config.deactivated_at is None)
            or (
                "revocation_effective_at" in raw
                and aware_timestamp(raw["revocation_effective_at"]) != config.deactivated_at
            )
        ):
            raise failure("BINDING_MISMATCH")

Resolved by trusted account/provider code, never decoded from buyer JSON.

The bound references are opaque; credentials stay in destination sessions. The SDK validates the complete frozen tuple before admitting configuration.

Instance variables

var binding : ReportingDestinationBinding
var configuration : ReportingConfiguration
var configuration_wire : Mapping[str, typing.Any]
var offering_id : str

Methods

def check(self,
support: ReportingProductionSupport) ‑> None
Expand source code
def check(self, support: ReportingProductionSupport) -> None:
    from adcp.reporting.ledger.store import reject_reserved_authoritative_party

    config, binding, raw = self.configuration, self.binding, self.wire()
    reject_reserved_authoritative_party(config)
    if raw.get("authoritative_party", "seller") != "seller":
        raise LedgerConflictError("UNSUPPORTED_FEATURE", "consumer authority is reserved")
    offering = support._configuration_offering(config, binding, offering_id=self.offering_id)
    schedule = offering.configuration_schedule(config)
    supplied_schedule = dict(raw["schedule"])
    if "period_anchor" in supplied_schedule:
        supplied_schedule["period_anchor"] = aware_timestamp(
            supplied_schedule["period_anchor"]
        ).isoformat()
        schedule["period_anchor"] = aware_timestamp(schedule["period_anchor"]).isoformat()
    scope = raw["scope"]
    # This producer freezes an explicit full media-buy denominator. An
    # application's dynamic all-buy or partial-coverage implementation must
    # not be represented as this installed exact-generation contract.
    if (
        raw["delivery_config_id"] != config.delivery_config_id
        or raw["delivery_config_version"] != config.delivery_config_version
        or raw["offering_id"] != self.offering_id
        or raw["feed_purpose"] != config.feed_purpose
        or raw["report_definition_id"] != config.report_definition_id
        or raw["reporting_profile"] != config.reporting_profile
        or raw["required_finality"] != config.required_finality
        or raw["reconciliation_mode"] != binding.reconciliation_mode
        or set(scope) != {"media_buy_ids"}
        or set(scope["media_buy_ids"]) != set(config.media_buy_ids)
        or raw["coverage_requirement"] != "full"
        or supplied_schedule != schedule
        or raw.get("method") != support._destination_binding(binding, offering).wire()
        or raw["active"] != (config.activated_at is not None and config.deactivated_at is None)
        or (
            "revocation_effective_at" in raw
            and aware_timestamp(raw["revocation_effective_at"]) != config.deactivated_at
        )
    ):
        raise failure("BINDING_MISMATCH")
def wire(self) ‑> dict[str, typing.Any]
Expand source code
def wire(self) -> dict[str, Any]:
    return dict(json.loads(self._wire))
class ReportingProductionConfigurationTask (handle: ConfigurationTask, account: AccountCapabilities)
Expand source code
@dataclass(frozen=True)
class ReportingProductionConfigurationTask:
    """Compose the account implementation with enforced SDK reporting admission.

    ``handle`` remains the application's authenticated, caller-owned desired
    state account task. It resolves provider grants and opaque bindings, calls
    the supplied ``admit`` for every accepted reporting generation, and returns
    the normal account response. The wrapper verifies returned ready states
    against the actual stored records and that call's validated admissions.
    A task cannot return a successful unsupported promise without a matching
    admitted configuration, including on exact replay.
    """

    handle: ConfigurationTask = field(repr=False)
    account: AccountCapabilities = field(repr=False, compare=False)
    _account_wire: bytes = field(init=False, repr=False)

    def __post_init__(self) -> None:
        from adcp.validation.schema_loader import get_named_validator

        raw = self.account.model_dump(mode="json", exclude_none=True, exclude_unset=True)
        validator = get_named_validator("protocol/get-adcp-capabilities-response.json")
        if (
            validator is None
            or next(
                validator.evolve(schema=validator.schema["properties"]["account"]).iter_errors(raw),
                None,
            )
            is not None
            or raw.get("account_financials") is True
            or any(
                raw.get(name, {}).get("supported") is True
                for name in ("notifications", "change_feed", "identity_updates")
            )
        ):
            raise ValueError(
                "configuration task requires its actual account capabilities and mounted operations"
            )
        object.__setattr__(self, "_account_wire", canonical_json_utf8_v1(raw))

    def account_capabilities(self) -> dict[str, Any]:
        return dict(json.loads(self._account_wire))

    async def execute(
        self,
        support: ReportingProductionSupport,
        request: dict[str, Any],
        context: ToolContext | None,
    ) -> dict[str, Any]:
        from adcp.validation.schema_loader import get_named_validator

        validator = get_named_validator("account/sync-accounts-request.json")
        if validator is None or next(validator.iter_errors(request), None) is not None:
            raise LedgerConflictError("INVALID_REQUEST", "account request is invalid")
        for entry in request["accounts"]:
            configurations = entry.get("reporting_delivery_configs", ())
            keys = [(c["delivery_config_id"], c["delivery_config_version"]) for c in configurations]
            if len(set(keys)) != len(keys):
                raise LedgerConflictError(
                    "INVALID_REQUEST", "configuration generations must be unique"
                )
        admitted: dict[tuple[str, str, str, int], ReportingConfigurationAdmission] = {}

        async def admit(value: ReportingConfigurationAdmission) -> None:
            if request.get("dry_run") is True:
                raise LedgerConflictError(
                    "INVALID_REQUEST", "dry runs cannot admit reporting state"
                )
            if type(value) is not ReportingConfigurationAdmission or context is None:
                raise LedgerConflictError("UNAUTHORIZED", "configuration authority is unavailable")
            who = await support.handler._authorize(
                {"account": {"account_id": value.configuration.account_id}}, context
            )
            if who != value.binding.principal:
                raise LedgerConflictError("UNAUTHORIZED", "configuration authority is unavailable")
            matched = False
            for entry in request["accounts"]:
                if "reporting_delivery_configs" not in entry or "account" not in entry:
                    continue
                try:
                    requested_caller = await support.handler._authorize(
                        {"account": entry["account"]}, context
                    )
                # An unresolved account cannot authorize this admission.
                except Exception:  # nosec B112
                    continue
                if requested_caller != who:
                    continue
                desired = entry["reporting_delivery_configs"]
                matched = value.wire() in desired or (
                    value.configuration.deactivated_at is not None
                    and not any(
                        (c["delivery_config_id"], c["delivery_config_version"])
                        == (
                            value.configuration.delivery_config_id,
                            value.configuration.delivery_config_version,
                        )
                        for c in desired
                    )
                )
                if matched:
                    break
            if not matched:
                raise LedgerConflictError(
                    "INVALID_REQUEST", "configuration differs from requested account state"
                )
            support.validate_configuration(value)
            await support._check_notifications(who.account_id)
            key = (
                who.account_id,
                who.consumer_id,
                value.configuration.delivery_config_id,
                value.configuration.delivery_config_version,
            )
            if key in admitted and admitted[key] != value:
                raise LedgerConflictError(
                    "CONFIGURATION_GENERATION_IMMUTABLE", "configuration identity conflicts"
                )
            await support._admit_configuration(value)
            # The caller already entered the migrated, drained production
            # lifecycle. Complete this account's versioned baseline before
            # echoing ready; adopters need no account-enumeration worker or
            # hand-maintained readiness flag. A failed activation remains
            # unready and can resume under the same durable identities.
            await support.activate(account_id=who.account_id)
            admitted[key] = value

        response = await self.handle(dict(request), context, admit)
        if not isinstance(response, Mapping):
            raise LedgerConflictError(
                "INVALID_REQUEST", "configuration task returned an invalid response"
            )
        if response.get("errors") or request.get("dry_run") is True:
            return dict(response)
        for account in response.get("accounts", ()):
            if account.get("action") == "failed":
                continue
            response_owner = await support.handler._authorize(
                {"account": {"account_id": account.get("account_id")}}, context
            )
            for state in account.get("reporting_delivery_configs", ()):
                if state.get("state") not in {"ready", "inactive"}:
                    continue
                config = state.get("configuration", {})
                key = (
                    response_owner.account_id,
                    response_owner.consumer_id,
                    config.get("delivery_config_id"),
                    config.get("delivery_config_version"),
                )
                value = admitted.get(key)
                if value is None:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration requires SDK admission"
                    )
                validator = get_named_validator("core/reporting-delivery-config-state.json")
                if (
                    validator is None
                    or next(validator.iter_errors(state), None) is not None
                    or config != value.wire()
                ):
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED",
                        "configuration state differs from admission",
                    )
                expected_state = (
                    "inactive" if value.configuration.deactivated_at is not None else "ready"
                )
                if state["state"] != expected_state:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration lifecycle differs"
                    )
                for name in ("activated_at", "deactivated_at"):
                    actual_time = getattr(value.configuration, name)
                    supplied = state.get(name)
                    if supplied is not None and aware_timestamp(supplied) != actual_time:
                        raise LedgerConflictError(
                            "REPORTING_CONFIGURATION_UNADMITTED", "configuration lifecycle differs"
                        )
                coverage = state.get("current_coverage")
                if state["state"] == "ready" and (
                    not isinstance(coverage, dict)
                    or coverage["status"] != "full"
                    or set(coverage["media_buy_ids"]) != set(value.configuration.media_buy_ids)
                    or set(coverage["fully_covered_media_buy_ids"])
                    != set(value.configuration.media_buy_ids)
                    or any(
                        coverage[k]
                        for k in (
                            "partially_covered_media_buy_ids",
                            "unsupported_media_buy_ids",
                            "unknown_media_buy_ids",
                            "unsupported_package_ids",
                            "unknown_package_ids",
                            "limitations",
                        )
                    )
                    or set(coverage["package_ids"]) != set(coverage["covered_package_ids"])
                ):
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration coverage differs"
                    )
                if state["state"] == "inactive":
                    from adcp.reporting.ledger.models import derive_period, first_ordinal_after

                    configuration = value.configuration
                    assert configuration.deactivated_at is not None
                    ordinal = first_ordinal_after(
                        configuration.schedule,
                        account_timezone=configuration.account_timezone,
                        activated_at=configuration.deactivated_at,
                    )
                    cutoff = derive_period(
                        configuration.schedule,
                        account_timezone=configuration.account_timezone,
                        ordinal=ordinal,
                    ).start
                    if aware_timestamp(state["publication_stopped_at"]) != cutoff:
                        raise LedgerConflictError(
                            "REPORTING_CONFIGURATION_UNADMITTED", "configuration cutoff differs"
                        )
                who = ReportingDeliveryPrincipal(
                    value.configuration.account_id, value.binding.consumer_id
                )
                actual = await support.store.get_destination_binding(
                    caller=who, generation_key=value.configuration.generation_key
                )
                configs = await support.store.list_configurations(caller=who)
                support.validate_configuration(value)
                if actual != value.binding or value.configuration not in configs:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED",
                        "configuration admission is unavailable",
                    )
                if state.get("destination_ref") != actual.destination_ref:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration destination differs"
                    )
        return dict(response)

Compose the account implementation with enforced SDK reporting admission.

handle remains the application's authenticated, caller-owned desired state account task. It resolves provider grants and opaque bindings, calls the supplied admit for every accepted reporting generation, and returns the normal account response. The wrapper verifies returned ready states against the actual stored records and that call's validated admissions. A task cannot return a successful unsupported promise without a matching admitted configuration, including on exact replay.

Instance variables

var account : Account
var handle : Callable[[dict[str, typing.Any], ToolContext | None, Callable[[ReportingConfigurationAdmission], Awaitable[None]]], Awaitable[dict[str, typing.Any]]]

Methods

def account_capabilities(self) ‑> dict[str, typing.Any]
Expand source code
def account_capabilities(self) -> dict[str, Any]:
    return dict(json.loads(self._account_wire))
async def execute(self,
support: ReportingProductionSupport,
request: dict[str, Any],
context: ToolContext | None) ‑> dict[str, Any]
Expand source code
async def execute(
    self,
    support: ReportingProductionSupport,
    request: dict[str, Any],
    context: ToolContext | None,
) -> dict[str, Any]:
    from adcp.validation.schema_loader import get_named_validator

    validator = get_named_validator("account/sync-accounts-request.json")
    if validator is None or next(validator.iter_errors(request), None) is not None:
        raise LedgerConflictError("INVALID_REQUEST", "account request is invalid")
    for entry in request["accounts"]:
        configurations = entry.get("reporting_delivery_configs", ())
        keys = [(c["delivery_config_id"], c["delivery_config_version"]) for c in configurations]
        if len(set(keys)) != len(keys):
            raise LedgerConflictError(
                "INVALID_REQUEST", "configuration generations must be unique"
            )
    admitted: dict[tuple[str, str, str, int], ReportingConfigurationAdmission] = {}

    async def admit(value: ReportingConfigurationAdmission) -> None:
        if request.get("dry_run") is True:
            raise LedgerConflictError(
                "INVALID_REQUEST", "dry runs cannot admit reporting state"
            )
        if type(value) is not ReportingConfigurationAdmission or context is None:
            raise LedgerConflictError("UNAUTHORIZED", "configuration authority is unavailable")
        who = await support.handler._authorize(
            {"account": {"account_id": value.configuration.account_id}}, context
        )
        if who != value.binding.principal:
            raise LedgerConflictError("UNAUTHORIZED", "configuration authority is unavailable")
        matched = False
        for entry in request["accounts"]:
            if "reporting_delivery_configs" not in entry or "account" not in entry:
                continue
            try:
                requested_caller = await support.handler._authorize(
                    {"account": entry["account"]}, context
                )
            # An unresolved account cannot authorize this admission.
            except Exception:  # nosec B112
                continue
            if requested_caller != who:
                continue
            desired = entry["reporting_delivery_configs"]
            matched = value.wire() in desired or (
                value.configuration.deactivated_at is not None
                and not any(
                    (c["delivery_config_id"], c["delivery_config_version"])
                    == (
                        value.configuration.delivery_config_id,
                        value.configuration.delivery_config_version,
                    )
                    for c in desired
                )
            )
            if matched:
                break
        if not matched:
            raise LedgerConflictError(
                "INVALID_REQUEST", "configuration differs from requested account state"
            )
        support.validate_configuration(value)
        await support._check_notifications(who.account_id)
        key = (
            who.account_id,
            who.consumer_id,
            value.configuration.delivery_config_id,
            value.configuration.delivery_config_version,
        )
        if key in admitted and admitted[key] != value:
            raise LedgerConflictError(
                "CONFIGURATION_GENERATION_IMMUTABLE", "configuration identity conflicts"
            )
        await support._admit_configuration(value)
        # The caller already entered the migrated, drained production
        # lifecycle. Complete this account's versioned baseline before
        # echoing ready; adopters need no account-enumeration worker or
        # hand-maintained readiness flag. A failed activation remains
        # unready and can resume under the same durable identities.
        await support.activate(account_id=who.account_id)
        admitted[key] = value

    response = await self.handle(dict(request), context, admit)
    if not isinstance(response, Mapping):
        raise LedgerConflictError(
            "INVALID_REQUEST", "configuration task returned an invalid response"
        )
    if response.get("errors") or request.get("dry_run") is True:
        return dict(response)
    for account in response.get("accounts", ()):
        if account.get("action") == "failed":
            continue
        response_owner = await support.handler._authorize(
            {"account": {"account_id": account.get("account_id")}}, context
        )
        for state in account.get("reporting_delivery_configs", ()):
            if state.get("state") not in {"ready", "inactive"}:
                continue
            config = state.get("configuration", {})
            key = (
                response_owner.account_id,
                response_owner.consumer_id,
                config.get("delivery_config_id"),
                config.get("delivery_config_version"),
            )
            value = admitted.get(key)
            if value is None:
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED", "configuration requires SDK admission"
                )
            validator = get_named_validator("core/reporting-delivery-config-state.json")
            if (
                validator is None
                or next(validator.iter_errors(state), None) is not None
                or config != value.wire()
            ):
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED",
                    "configuration state differs from admission",
                )
            expected_state = (
                "inactive" if value.configuration.deactivated_at is not None else "ready"
            )
            if state["state"] != expected_state:
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED", "configuration lifecycle differs"
                )
            for name in ("activated_at", "deactivated_at"):
                actual_time = getattr(value.configuration, name)
                supplied = state.get(name)
                if supplied is not None and aware_timestamp(supplied) != actual_time:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration lifecycle differs"
                    )
            coverage = state.get("current_coverage")
            if state["state"] == "ready" and (
                not isinstance(coverage, dict)
                or coverage["status"] != "full"
                or set(coverage["media_buy_ids"]) != set(value.configuration.media_buy_ids)
                or set(coverage["fully_covered_media_buy_ids"])
                != set(value.configuration.media_buy_ids)
                or any(
                    coverage[k]
                    for k in (
                        "partially_covered_media_buy_ids",
                        "unsupported_media_buy_ids",
                        "unknown_media_buy_ids",
                        "unsupported_package_ids",
                        "unknown_package_ids",
                        "limitations",
                    )
                )
                or set(coverage["package_ids"]) != set(coverage["covered_package_ids"])
            ):
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED", "configuration coverage differs"
                )
            if state["state"] == "inactive":
                from adcp.reporting.ledger.models import derive_period, first_ordinal_after

                configuration = value.configuration
                assert configuration.deactivated_at is not None
                ordinal = first_ordinal_after(
                    configuration.schedule,
                    account_timezone=configuration.account_timezone,
                    activated_at=configuration.deactivated_at,
                )
                cutoff = derive_period(
                    configuration.schedule,
                    account_timezone=configuration.account_timezone,
                    ordinal=ordinal,
                ).start
                if aware_timestamp(state["publication_stopped_at"]) != cutoff:
                    raise LedgerConflictError(
                        "REPORTING_CONFIGURATION_UNADMITTED", "configuration cutoff differs"
                    )
            who = ReportingDeliveryPrincipal(
                value.configuration.account_id, value.binding.consumer_id
            )
            actual = await support.store.get_destination_binding(
                caller=who, generation_key=value.configuration.generation_key
            )
            configs = await support.store.list_configurations(caller=who)
            support.validate_configuration(value)
            if actual != value.binding or value.configuration not in configs:
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED",
                    "configuration admission is unavailable",
                )
            if state.get("destination_ref") != actual.destination_ref:
                raise LedgerConflictError(
                    "REPORTING_CONFIGURATION_UNADMITTED", "configuration destination differs"
                )
    return dict(response)
class ReportingProductionDestination (*args, **kwargs)
Expand source code
@runtime_checkable
class ReportingProductionDestination(
    ReportingDestinationWriter, ReportingDestinationResolver, Protocol
):
    """An actual provider's bounded retention and revocation commitments.

    These promises accompany the writer's exact capabilities. Every write and
    independent readback still opens a separately authorized SDK session. A
    service cannot make the development writer eligible by decorating it.
    """

    @property
    def resource_retention_days(self) -> int: ...

    @property
    def authorization_revocation_seconds(self) -> int: ...

    @property
    def delivery_methods(self) -> tuple[ReportingProductionMethod, ...]: ...

    def configuration_binding(
        self, binding: ReportingDestinationBinding
    ) -> ReportingProductionDestinationBinding | None: ...

An actual provider's bounded retention and revocation commitments.

These promises accompany the writer's exact capabilities. Every write and independent readback still opens a separately authorized SDK session. A service cannot make the development writer eligible by decorating it.

Ancestors

Instance variables

prop authorization_revocation_seconds : int
Expand source code
@property
def authorization_revocation_seconds(self) -> int: ...
prop delivery_methods : tuple[ReportingProductionMethod, ...]
Expand source code
@property
def delivery_methods(self) -> tuple[ReportingProductionMethod, ...]: ...
prop resource_retention_days : int
Expand source code
@property
def resource_retention_days(self) -> int: ...

Methods

def configuration_binding(self, binding: ReportingDestinationBinding) ‑> ReportingProductionDestinationBinding | None
Expand source code
def configuration_binding(
    self, binding: ReportingDestinationBinding
) -> ReportingProductionDestinationBinding | None: ...
class ReportingProductionDestinationBinding (binding: ReportingDestinationBinding,
method: ReportingProductionMethod,
configuration: Mapping[str, Any])
Expand source code
@dataclass(frozen=True)
class ReportingProductionDestinationBinding:
    """The provider's authorized, immutable destination contract for a caller.

    ``configuration`` is the complete secret-free public delivery method,
    including the selected destination. The provider resolves it from its
    trusted binding, not from a buyer's claim. Credentials remain in the
    independently authorized write/readback sessions. The SDK freezes these
    bytes at admission and compares them again before materialization.
    """

    binding: ReportingDestinationBinding = field(repr=False)
    method: ReportingProductionMethod
    configuration: Mapping[str, Any] = field(repr=False, compare=False)
    _wire: bytes = field(init=False, repr=False)

    def __post_init__(self) -> None:
        from adcp.reporting.evidence import consumer_reference, resource_location
        from adcp.validation.schema_loader import get_named_validator

        if (
            type(self.binding) is not ReportingDestinationBinding
            or type(self.method) is not ReportingProductionMethod
        ):
            raise ValueError("destination requires the exact provider binding and method")
        raw = json.loads(canonical_json_utf8_v1(dict(self.configuration)))
        validator = get_named_validator("core/reporting-delivery-method.json")
        offered = self.method.wire()
        if (
            validator is None
            or next(validator.iter_errors(raw), None) is not None
            or any(raw.get(k) != offered.get(k) for k in ("pattern", "transport", "orchestration"))
            or (raw["pattern"] == "file_transfer" and raw["format"] != offered.get("format"))
            or raw["destination"]["mode"] not in offered["destination_modes"]
        ):
            raise ValueError("destination must match the provider's complete method")
        destination = raw["destination"]
        if destination["mode"] == "existing":
            if destination["destination_ref"] != self.binding.destination_ref:
                raise ValueError("destination must match the immutable binding")
        elif destination.get("provider") != offered.get("provider") or destination.get(
            "access_mode"
        ) != offered.get("access_mode"):
            raise ValueError("destination must match the provider's complete method")
        if "location" in destination:
            resource_location(destination["location"])
        if "recipient" in destination:
            consumer_reference(destination["recipient"]["identity"])
        object.__setattr__(self, "_wire", canonical_json_utf8_v1(raw))

    def wire(self) -> dict[str, Any]:
        return dict(json.loads(self._wire))

The provider's authorized, immutable destination contract for a caller.

adcp.reporting.production.configuration is the complete secret-free public delivery method, including the selected destination. The provider resolves it from its trusted binding, not from a buyer's claim. Credentials remain in the independently authorized write/readback sessions. The SDK freezes these bytes at admission and compares them again before materialization.

Instance variables

var binding : ReportingDestinationBinding
var configuration : Mapping[str, typing.Any]
var method : ReportingProductionMethod

Methods

def wire(self) ‑> dict[str, typing.Any]
Expand source code
def wire(self) -> dict[str, Any]:
    return dict(json.loads(self._wire))
class ReportingProductionHandler (production: ReportingProductionSupport,
*,
resolve_account: ReceiptAccountResolver,
buyer_agents: BuyerAgentRegistry | None = None,
adcp_version: str | None = None)
Expand source code
class ReportingProductionHandler(ReportingReceiptHandler):
    """Mount the same instance on MCP/A2A; the support owns its lifecycle."""

    advertised_tools = _REPORTING_TASKS | _APPLICATION_TASKS

    def __init__(
        self,
        production: ReportingProductionSupport,
        *,
        resolve_account: ReceiptAccountResolver,
        buyer_agents: BuyerAgentRegistry | None = None,
        adcp_version: str | None = None,
    ) -> None:
        self.production = production
        self._application: ADCPHandler[Any] | None = None
        self._application_tools: frozenset[str] = frozenset()
        super().__init__(
            production.store,
            resolve_account=resolve_account,
            buyer_agents=buyer_agents,
            consumer_status_enabled=production.projection.consumer_status_enabled,
            adcp_version=adcp_version,
        )

    def bind_application(self, application: ADCPHandler[Any]) -> None:
        """Delegate ordinary tasks before mounting this exact SDK handler.

        Reporting/configuration collisions are refused. Supply the typed B2
        configuration task separately; aggregate delivery and base capabilities
        may coexist and are dispatched explicitly by their protected methods.
        """
        if application is self or not isinstance(application, ADCPHandler):
            raise ValueError("application must be a separate ADCPHandler")
        if self._application is application:
            return
        if (
            self._application is not None
            or self.production._mounts
            or self.production._task is not None
        ):
            raise ValueError("application delegation must be fixed before mounting")
        names = {t["name"] for t in get_tools_for_handler(application, _include_schemas=False)}
        if names & (_REPORTING_TASKS - {"get_adcp_capabilities", "get_media_buy_delivery"}):
            raise ValueError("application reporting handlers conflict with production ownership")
        version = getattr(application, "get_adcp_version", None)
        if callable(version) and version() != self.get_adcp_version():
            raise ValueError("application and production protocol versions differ")
        self._application, self._application_tools = application, frozenset(names)

    async def _delegate(self, task: str, params: Any, context: ToolContext | None) -> Any:
        if self._application is None or task not in self._application_tools:
            return self._not_supported(task)
        result = getattr(self._application, _APPLICATION_METHODS.get(task, task))(params, context)
        return await result if inspect.isawaitable(result) else result

    def advertised_tools_for_instance(self) -> set[str]:
        names = {
            "get_adcp_capabilities",
            "get_reporting_status",
            "get_media_buy_delivery",
            "sync_accounts",
        }
        if any(o.reconciled for o in self.production.offerings):
            names.add("sync_reporting_receipts")
        if self._feed_consumer_status_enabled:
            names.add("sync_reporting_status")
        return names | set(self._application_tools & _APPLICATION_TASKS)

    @_admitted
    async def get_reporting_status(
        self,
        params: GetReportingStatusRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any] | NotImplementedResponse:
        return await super().get_reporting_status(params, context)

    @_admitted
    async def sync_reporting_receipts(
        self,
        params: SyncReportingReceiptsRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any]:
        if not any(o.reconciled for o in self.production.offerings):
            raise _task_error(
                "sync_reporting_receipts", "NOT_SUPPORTED", "receipt task is unavailable"
            )
        return await super().sync_reporting_receipts(params, context)

    async def _authorize(
        self, request: dict[str, Any], context: ToolContext | None
    ) -> ReportingDeliveryPrincipal:
        try:
            if context is None or not isinstance(request.get("account"), dict):
                raise ReportingReceiptError("UNAUTHORIZED")
            consumer = await _consumer(context, self._receipt_registry)
            account = await self._receipt_account_resolver(
                dict(request["account"]), context, consumer
            )
            if isinstance(context, RequestContext) and context.account.id != account:
                raise ReportingReceiptError("UNAUTHORIZED")
            return ReportingDeliveryPrincipal(account, consumer)
        except (ReliableReportingConfigurationError, ReliableReportingUnavailableError):
            raise
        except Exception:
            raise ReportingReceiptError("UNAUTHORIZED") from None

    async def get_adcp_capabilities(
        self,
        params: GetAdcpCapabilitiesRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any]:
        response = capabilities_response(
            ["media_buy"],
            sandbox=False,
            idempotency={"supported": False},
            adcp_version=self.production._protocol_version,
            supported_versions=[self.production._protocol_version],
        )
        if self._application is not None and "get_adcp_capabilities" in self._application_tools:
            protocol = response["adcp"]
            result = await self._delegate("get_adcp_capabilities", params, context)
            base = {} if isinstance(result, NotImplementedResponse) else _request(result)
            if (base.get("media_buy") or {}).get("reporting_delivery") is not None:
                raise ValueError(
                    "application reporting capabilities conflict with production ownership"
                )
            response.update(base)
            response["adcp_version"] = self.production._protocol_version
            response["adcp"] = {
                **response["adcp"],
                "major_versions": protocol["major_versions"],
                "supported_versions": protocol["supported_versions"],
            }
            response["supported_protocols"] = list(
                dict.fromkeys([*base.get("supported_protocols", ()), "media_buy"])
            )
        response["account"] = self.production.configuration_task.account_capabilities()
        declaration = self.production._declared_capabilities()
        reporting = declaration["reporting_delivery"]
        if reporting:
            response["media_buy"] = {
                **response.get("media_buy", {}),
                "reporting_delivery": reporting,
            }
            response["experimental_features"] = list(
                dict.fromkeys(
                    [*response.get("experimental_features", ()), "media_buy.reporting_delivery"]
                )
            )
            if any(
                reporting.get(k)
                for k in ("ledger_notification", "status_notification", "readiness_notification")
            ):
                response["webhook_signing"] = declaration["webhook_signing"]
                response["identity"] = declaration["identity"]
        return response

    @_admitted
    async def sync_accounts(
        self,
        params: SyncAccountsRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any]:
        try:
            self.production._assert_components()
            return await self.production.configuration_task.execute(
                self.production, _request(params), context
            )
        except LedgerConflictError as error:
            code, message = error.code, str(error)
        except ReportingReceiptError as error:
            code, message = error.code, str(error)
        except (ReliableReportingConfigurationError, ReliableReportingUnavailableError):
            raise
        except Exception:
            code, message = (
                "REPORTING_CONFIGURATION_UNAVAILABLE",
                "reporting configuration is unavailable",
            )
        raise _task_error("sync_accounts", code, message)

    @_admitted
    async def sync_reporting_status(
        self,
        params: SyncReportingStatusRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any] | NotImplementedResponse:
        if not self._feed_consumer_status_enabled:
            return self._not_supported("sync_reporting_status")
        try:
            request = _request(params)
            caller = await self._authorize(request, context)
            result = await ConsumerStatusIngest(self.production.store, enabled=True).handle(
                request,
                account_id=caller.account_id,
                consumer_id=caller.consumer_id,
            )
            if await self._authorize(request, context) != caller:
                raise ReportingReceiptError("UNAUTHORIZED")
            return result
        except (ReportingReceiptError, LedgerConflictError) as error:
            code, message = error.code, str(error)
        except (ReliableReportingConfigurationError, ReliableReportingUnavailableError):
            raise
        except Exception:
            code, message = "REPORTING_STATUS_UNAVAILABLE", "reporting status is unavailable"
        raise _task_error("sync_reporting_status", code, message)

    @_admitted
    async def get_media_buy_delivery(
        self,
        params: GetMediaBuyDeliveryRequest | dict[str, Any],
        context: ToolContext | None = None,
    ) -> dict[str, Any] | NotImplementedResponse:
        request = _request(params)
        if "reporting_revision_id" not in request:
            return cast(
                dict[str, Any] | NotImplementedResponse,
                await self._delegate("get_media_buy_delivery", params, context),
            )
        try:
            from adcp.validation.schema_loader import get_named_validator

            validator = get_named_validator("media-buy/get-media-buy-delivery-request.json")
            if validator is None or next(validator.iter_errors(request), None) is not None:
                raise LedgerConflictError("INVALID_REQUEST", "exact revision request is invalid")
            caller = await self._authorize(request, context)
            revision_id = request["reporting_revision_id"]
            status_request = {
                "account": request["account"],
                "view": "revision",
                "reporting_revision_id": revision_id,
            }
            # This is the actual private mounted status path, including exact
            # ownership/visibility and complete captured reconciliation checks.
            projected = await self.get_reporting_status(status_request, context)
            if not isinstance(projected, dict) or "revision" not in projected:
                raise LedgerConflictError("REFERENCE_NOT_FOUND", "no such revision is available")
            store = self.production.store
            revision = await store.get_revision(
                account_id=caller.account_id, reporting_revision_id=revision_id
            )
            if revision is None:
                raise LedgerConflictError("REFERENCE_NOT_FOUND", "no such revision is available")
            if not revision.readable:
                # A retained revision this seller still owes but cannot serve is never
                # not-found, and never rows that fail the binding.
                raise ReportingRowStoreError("ROWS_UNAVAILABLE", "revision rows are unreadable")
            pagination = request.get("pagination") or {}
            limit = pagination.get("max_results", 50)
            if type(limit) is not int or not 1 <= limit <= 100:
                raise LedgerConflictError("INVALID_REQUEST", "exact revision page size is invalid")
            binding_hash = hashlib.sha256(
                canonical_json_utf8_v1(
                    {
                        "account": caller.account_id,
                        "consumer": caller.consumer_id,
                        "revision": revision_id,
                        "digest": revision.revision_content_sha256,
                        "count": revision.row_count,
                        "ownership": 2,
                        "limit": limit,
                    }
                )
            ).hexdigest()
            token = pagination.get("cursor")
            offset = 0
            if token is not None:
                if not isinstance(token, str) or not token.startswith("rpr2.") or len(token) > 2048:
                    raise LedgerConflictError(
                        "INVALID_CURSOR", "exact revision cursor is unavailable"
                    )
                cursor = decode_cursor(token[5:])
                if cursor.get("ownership") != 2:
                    raise ADCPTaskError(
                        "get_media_buy_delivery",
                        [
                            {
                                "code": "INVALID_CHECKPOINT",
                                "message": "Restart revision pagination without the legacy cursor.",
                                "recovery": "correctable",
                            }
                        ],
                    )
                if (
                    set(cursor) != {"v", "h", "p", "ownership"}
                    or cursor["v"] != 2
                    or cursor["ownership"] != 2
                    or cursor["h"] != binding_hash
                    or type(cursor["p"]) is not int
                    or not 0 <= cursor["p"] <= revision.row_count
                ):
                    raise LedgerConflictError(
                        "INVALID_CURSOR", "exact revision cursor is unavailable"
                    )
                offset = cursor["p"]
            page = await store.read_revision_rows(
                account_id=caller.account_id,
                reporting_revision_id=revision_id,
                limit=limit,
                cursor=(
                    encode_cursor({"ownership": 2, "revision": revision_id, "offset": offset})
                    if offset
                    else None
                ),
            )
            if page.total_count != revision.row_count or page.reporting_revision_id != revision_id:
                raise ReportingNotificationError("reporting_revision_content_unavailable")
            if await self._authorize(request, context) != caller:
                raise ReportingReceiptError("UNAUTHORIZED")
            after = await store.get_revision(
                account_id=caller.account_id, reporting_revision_id=revision_id
            )
            if after != revision:
                raise LedgerConflictError("REFERENCE_NOT_FOUND", "no such revision is available")
            wire = projected["revision"]
            totals = (
                [r.to_wire() for r in revision.managed_control_totals]
                if revision.managed_control_totals is not None
                else [{"name": n, "value": v} for n, v in revision.control_totals]
            )
            position: dict[str, Any] = {"total_count": page.total_count, "has_more": page.has_more}
            if page.has_more:
                position["cursor"] = "rpr2." + encode_cursor(
                    {"v": 2, "ownership": 2, "h": binding_hash, "p": offset + len(page.rows)}
                )
            result = {
                "status": "completed",
                "reporting_period": {
                    "start": wire["period"]["start"],
                    "end": wire["period"]["end"],
                },
                "media_buy_deliveries": [],
                "reporting_revision": wire,
                "reporting_revision_binding": {
                    "reporting_revision_id": revision_id,
                    "row_count": revision.row_count,
                    "control_totals": totals,
                    "content_sha256": revision.revision_content_sha256,
                },
                "reporting_rows": list(page.rows),
                "pagination": position,
            }
            if "ext" in projected:
                result["ext"] = projected["ext"]
            return result
        except ADCPTaskError:
            raise
        except (ReportingReceiptError, LedgerConflictError) as error:
            code, message = error.code, str(error)
        except (ReliableReportingConfigurationError, ReliableReportingUnavailableError):
            raise
        except Exception as error:
            if isinstance(error, ReportingRowStoreError) or (
                isinstance(error, ReportingNotificationError)
                and error.code == "reporting_revision_content_unavailable"
            ):
                # Operator codes never reach a buyer, so a buyer cannot probe whether an
                # object exists. Rows that are missing or fail their binding inside the
                # retention window are SERVICE_UNAVAILABLE, never not-found.
                code = "SERVICE_UNAVAILABLE"
                message = "reporting revision rows are temporarily unavailable"
            else:
                code, message = "REPORTING_CONTENT_UNAVAILABLE", "reporting content is unavailable"
        raise _task_error("get_media_buy_delivery", code, message)

Mount the same instance on MCP/A2A; the support owns its lifecycle.

Ancestors

Class variables

var advertised_tools

Methods

def advertised_tools_for_instance(self) ‑> set[str]
Expand source code
def advertised_tools_for_instance(self) -> set[str]:
    names = {
        "get_adcp_capabilities",
        "get_reporting_status",
        "get_media_buy_delivery",
        "sync_accounts",
    }
    if any(o.reconciled for o in self.production.offerings):
        names.add("sync_reporting_receipts")
    if self._feed_consumer_status_enabled:
        names.add("sync_reporting_status")
    return names | set(self._application_tools & _APPLICATION_TASKS)
def bind_application(self, application: ADCPHandler[Any]) ‑> None
Expand source code
def bind_application(self, application: ADCPHandler[Any]) -> None:
    """Delegate ordinary tasks before mounting this exact SDK handler.

    Reporting/configuration collisions are refused. Supply the typed B2
    configuration task separately; aggregate delivery and base capabilities
    may coexist and are dispatched explicitly by their protected methods.
    """
    if application is self or not isinstance(application, ADCPHandler):
        raise ValueError("application must be a separate ADCPHandler")
    if self._application is application:
        return
    if (
        self._application is not None
        or self.production._mounts
        or self.production._task is not None
    ):
        raise ValueError("application delegation must be fixed before mounting")
    names = {t["name"] for t in get_tools_for_handler(application, _include_schemas=False)}
    if names & (_REPORTING_TASKS - {"get_adcp_capabilities", "get_media_buy_delivery"}):
        raise ValueError("application reporting handlers conflict with production ownership")
    version = getattr(application, "get_adcp_version", None)
    if callable(version) and version() != self.get_adcp_version():
        raise ValueError("application and production protocol versions differ")
    self._application, self._application_tools = application, frozenset(names)

Delegate ordinary tasks before mounting this exact SDK handler.

Reporting/configuration collisions are refused. Supply the typed B2 configuration task separately; aggregate delivery and base capabilities may coexist and are dispatched explicitly by their protected methods.

Inherited members

class ReportingProductionMethod (capability: ReportingWriterCapability, method: Mapping[str, Any])
Expand source code
@dataclass(frozen=True)
class ReportingProductionMethod:
    """The actual provider's complete public method for one writer capability.

    This includes the provider, destination modes, access/producer identity and
    reader requirements. A method advertised by an offering must equal this
    declaration. The copied bytes cannot change through an adopter's mapping.
    Runtime writer, resolver, verifier and authorization checks remain required.
    """

    capability: ReportingWriterCapability
    method: Mapping[str, Any] = field(repr=False, compare=False)
    _wire: bytes = field(init=False, repr=False)

    def __post_init__(self) -> None:
        from adcp.validation.schema_loader import get_named_validator

        raw = json.loads(canonical_json_utf8_v1(dict(self.method)))
        validator = get_named_validator("core/reporting-delivery-offering.json")
        if (
            validator is None
            or next(
                validator.evolve(schema=validator.schema["properties"]["method"]).iter_errors(raw),
                None,
            )
            is not None
            or raw.get("orchestration") != "producer_managed"
            or (raw.get("pattern"), raw.get("transport"), raw.get("format"))
            != (self.capability.method, self.capability.transport, self.capability.format)
        ):
            raise ValueError("production method must match the provider's exact writer capability")
        object.__setattr__(self, "_wire", canonical_json_utf8_v1(raw))

    def wire(self) -> dict[str, Any]:
        return dict(json.loads(self._wire))

The actual provider's complete public method for one writer capability.

This includes the provider, destination modes, access/producer identity and reader requirements. A method advertised by an offering must equal this declaration. The copied bytes cannot change through an adopter's mapping. Runtime writer, resolver, verifier and authorization checks remain required.

Instance variables

var capability : ReportingWriterCapability
var method : Mapping[str, typing.Any]

Methods

def wire(self) ‑> dict[str, typing.Any]
Expand source code
def wire(self) -> dict[str, Any]:
    return dict(json.loads(self._wire))
class ReportingProductionOffering (offering: ReportingDeliveryOffering,
producer: ReportingProducer,
verification_key: ReportingVerificationKey,
source_offering_id: str)
Expand source code
@dataclass(frozen=True)
class ReportingProductionOffering:
    """One public offering and the exact running components that implement it.

    The wire model is copied into immutable bytes so mutating an adopter's
    Pydantic model after construction cannot change the advertised contract.
    Capability availability is still checked against live components.
    """

    offering: ReportingDeliveryOffering = field(repr=False, compare=False)
    producer: ReportingProducer = field(repr=False, compare=False)
    verification_key: ReportingVerificationKey
    source_offering_id: str
    _wire: bytes = field(init=False, repr=False)
    _producer_key: str = field(init=False, repr=False)
    _source_identity: int = field(init=False, repr=False)
    _reader_identity: int = field(init=False, repr=False)

    def __post_init__(self) -> None:
        checked = ReportingDeliveryOffering.model_validate(
            self.offering.model_dump(mode="json", exclude_none=True)
        )
        raw = checked.model_dump(mode="json", exclude_none=True)
        from adcp.validation.schema_loader import get_named_validator

        validator = get_named_validator("core/reporting-delivery-offering.json")
        if validator is None or next(validator.iter_errors(raw), None) is not None:
            raise ValueError("offering must satisfy the complete public contract")
        profile, definition, key = (
            raw["reporting_profile"],
            self.verification_key.definition,
            self.verification_key,
        )
        method = raw.get("method")
        if (
            method is None
            or method.get("orchestration") != "producer_managed"
            or (method["pattern"], method["transport"], method.get("format"))
            != (key.capability.method, key.capability.transport, key.capability.format)
            or (raw["report_definition_id"], profile["id"])
            != (key.report_definition_id, key.reporting_profile)
            or (raw["report_definition_uri"], raw["report_definition_sha256"].lower())
            != (definition.report_definition_uri, definition.report_definition_sha256)
            or (
                profile["version"],
                profile["schema_uri"],
                profile["schema_sha256"].lower(),
                profile["schema_dialect"],
                profile["schema_ref_policy"],
            )
            != (
                definition.schema_version,
                definition.schema_uri,
                definition.schema_sha256,
                definition.schema_dialect,
                definition.schema_ref_policy,
            )
            or not raw["supported_finality"]
            or len(set(raw["supported_finality"])) != len(raw["supported_finality"])
        ):
            raise ValueError("offering must match its installed producer and exact verifier")
        if raw["reconciliation_mode"] == "consumer_receipt":
            if (
                raw["supported_finality"] != ["official"]
                or key.capability.verification_profile != "canonical_digest"
                or (
                    profile.get("canonicalization_id"),
                    profile.get("canonicalization_uri"),
                    str(profile.get("canonicalization_sha256", "")).lower(),
                )
                != (
                    key.canonicalization.canonicalization_id,
                    key.canonicalization.canonicalization_uri,
                    key.canonicalization.canonicalization_sha256,
                )
            ):
                raise ValueError("reconciled offerings require official canonical receipt evidence")
        elif raw["feed_purpose"] == "billing":
            raise ValueError("billing offerings require consumer receipts")
        object.__setattr__(self, "_wire", canonical_json_utf8_v1(raw))
        object.__setattr__(self, "_source_identity", id(self.producer._source))
        object.__setattr__(self, "_reader_identity", id(self.producer._object_reader))
        object.__setattr__(
            self,
            "_producer_key",
            hashlib.sha256(
                canonical_json_utf8_v1(
                    {
                        "offering": raw,
                        "source_offering_id": self.source_offering_id,
                        "publication_namespace": self.producer._offerings.publication_namespace,
                        "source_scope": dict(self.producer._offerings.source_scope),
                    }
                )
            ).hexdigest(),
        )
        self.check_source()

    @property
    def offering_id(self) -> str:
        return str(self.wire()["offering_id"])

    @property
    def reconciled(self) -> bool:
        return bool(self.wire()["reconciliation_mode"] == "consumer_receipt")

    def wire(self) -> dict[str, Any]:
        return dict(json.loads(self._wire))

    def check_source(self, *, effective: bool = False) -> ReportingSourceCapabilitiesV1:
        source = self.producer._source
        if (
            id(source) != self._source_identity
            or not isinstance(source, ReportingProductionSource)
            or id(self.producer._object_reader) != self._reader_identity
            or not isinstance(self.producer._object_reader, ReportingSourceStagedObjectReader)
        ):
            raise failure("BINDING_MISMATCH")
        capabilities = ReportingSourceCapabilitiesV1.model_validate(
            source.capabilities.model_dump(mode="json", exclude_none=True)
        )
        if effective and capabilities.scope != "effective_account":
            raise failure("BINDING_MISMATCH")
        raw = self.wire()
        source_offering = capabilities.offering(self.source_offering_id)
        contract, key = source_offering.contract, self.verification_key
        source_values = contract.model_dump(mode="json")
        expected = {
            "report_definition_id": key.report_definition_id,
            "reporting_profile": key.reporting_profile,
        }
        expected.update(
            {
                name: getattr(key.definition, name)
                for name in (
                    "report_definition_uri",
                    "report_definition_sha256",
                    "schema_version",
                    "schema_uri",
                    "schema_sha256",
                    "schema_dialect",
                    "schema_ref_policy",
                )
            }
        )
        finality = raw["supported_finality"]
        configured = self.producer._offerings
        if (
            any(source_values.get(name) != value for name, value in expected.items())
            or source_offering.publication_namespace != configured.publication_namespace
            or dict(configured.source_scope) != capabilities.source_scope
            or not source_offering.provider_execution.supports_cancellation
            or (
                "official" in finality
                and (
                    not isinstance(source_offering, AuthoritativeOfferingV1)
                    or configured.official_offering_id != self.source_offering_id
                    or (
                        self.reconciled
                        and source_offering.correction_policy != "immutable_correction"
                    )
                )
            )
            or (
                "snapshot" in finality
                and (
                    not isinstance(source_offering, ProvisionalSnapshotOfferingV1)
                    or configured.snapshot_offering_id != self.source_offering_id
                )
            )
        ):
            raise failure("UNSUPPORTED_VERIFICATION")
        schedule = raw["schedule"]
        duration = iso_duration_milliseconds_v1(schedule["period_duration"])
        if not (
            iso_duration_milliseconds_v1(source_offering.windowing.minimum_window)
            <= duration
            <= iso_duration_milliseconds_v1(source_offering.windowing.maximum_window)
        ) or iso_duration_milliseconds_v1(schedule["delivery_sla"]) < iso_duration_milliseconds_v1(
            source_offering.worst_case_availability_lag
        ):
            raise failure("UNSUPPORTED_VERIFICATION")
        if isinstance(
            source_offering, ProvisionalSnapshotOfferingV1
        ) and duration < iso_duration_milliseconds_v1(source_offering.fastest_safe_cadence):
            raise failure("UNSUPPORTED_VERIFICATION")
        if (
            schedule["alignment"] == "source_timezone"
            and schedule.get("period_timezone") != source_offering.source_timezone
        ):
            raise failure("UNSUPPORTED_VERIFICATION")
        return capabilities

    def source_binding(
        self, configuration: ReportingConfiguration
    ) -> ReportingProductionSourceBinding:
        require_account_work(configuration.account_id)
        try:
            capabilities = self.check_source(effective=True)
            source = self.producer._source
            assert isinstance(source, ReportingProductionSource)
            binding = source.configuration_binding(configuration)
            if binding is None:
                # Discovery can probe several generations before selecting a
                # dispatch. Refuse this candidate without revoking a turn that
                # may select another one; the producer's dispatch/publication
                # checks own the account-wide stop after a live denial.
                raise _SourceAuthorizationRevokedError()
            if type(binding) is not ReportingProductionSourceBinding:
                raise failure("BINDING_MISMATCH")
            binding.check(configuration, capabilities, self.source_offering_id)
            return binding
        except _SourceAuthorizationRevokedError:
            raise
        except Exception:
            raise failure("BINDING_MISMATCH") from None

    def configuration_schedule(self, configuration: ReportingConfiguration) -> dict[str, Any]:
        """Project a proven legacy clock into the public schedule vocabulary.

        Existing captured clocks and their closed storage decoder stay intact.
        New production admission requires the normative public phase; an old
        explicit anchor is compatible only when it produces the same periods.
        Calendar-month/year clocks unsupported by that decoder are refused.
        """
        offered = self.wire()["schedule"]
        schedule = configuration.schedule
        alignment = offered["alignment"]
        expected_alignment = (
            alignment if alignment in {"utc", "account_timezone"} else "custom_timezone"
        )
        zone, duration, anchor = _schedule_clock(schedule, configuration.account_timezone)
        if (
            schedule.alignment != expected_alignment
            or schedule.period_duration != offered["period_duration"]
            or schedule.delivery_sla != offered["delivery_sla"]
            or (alignment != "billing_cycle" and (anchor - datetime(1970, 1, 1)) % duration)
            or (alignment == "billing_cycle" and schedule.period_anchor is None)
        ):
            raise failure("BINDING_MISMATCH")
        result: dict[str, Any] = {
            "period_duration": schedule.period_duration,
            "delivery_sla": schedule.delivery_sla,
            "alignment": alignment,
        }
        if alignment in {"source_timezone", "billing_cycle"}:
            result["period_timezone"] = zone.key
        if alignment == "billing_cycle":
            assert schedule.period_anchor is not None
            result["period_anchor"] = schedule.period_anchor.isoformat()
        if (
            offered.get("period_timezone_policy") == "fixed"
            or offered.get("period_anchor_policy") == "fixed"
        ) and result.get("period_timezone") != offered.get("period_timezone"):
            raise failure("BINDING_MISMATCH")
        if offered.get(
            "period_anchor_policy"
        ) == "fixed" and schedule.period_anchor != aware_timestamp(offered["period_anchor"]):
            raise failure("BINDING_MISMATCH")
        if (
            alignment == "source_timezone"
            and zone.key
            != self.check_source(effective=True).offering(self.source_offering_id).source_timezone
        ):
            raise failure("BINDING_MISMATCH")
        return result

    def check_configuration(
        self,
        configuration: ReportingConfiguration,
        binding: ReportingDestinationBinding,
        *,
        retention_days: int,
    ) -> None:
        capabilities = self.check_source(effective=True)
        self.source_binding(configuration)
        self.configuration_schedule(configuration)
        raw, key = self.wire(), self.verification_key
        schedule, offered = configuration.schedule, raw["schedule"]
        if (
            binding.generation_key != configuration.generation_key
            or (
                configuration.report_definition_id,
                configuration.reporting_profile,
                configuration.feed_purpose,
                configuration.required_finality,
            )
            != (
                key.report_definition_id,
                key.reporting_profile,
                raw["feed_purpose"],
                raw["supported_finality"][0],
            )
            or not _same_definition(key, configuration.definition)
            or configuration.authoritative_party != "seller"
            or binding.reconciliation_mode != raw["reconciliation_mode"]
            or binding.feed_purpose != raw["feed_purpose"]
            or (binding.method, binding.transport, binding.format, binding.verification_profile)
            != (
                key.capability.method,
                key.capability.transport,
                key.capability.format,
                key.capability.verification_profile,
            )
            or binding.resource_retention_days != retention_days
            or binding.reader_compatibility != tuple(raw["method"].get("reader_compatibility", ()))
            or schedule.period_duration != offered["period_duration"]
            or iso_duration_to_timedelta(schedule.delivery_sla)
            != iso_duration_to_timedelta(offered["delivery_sla"])
            or iso_duration_milliseconds_v1(schedule.delivery_sla)
            < iso_duration_milliseconds_v1(
                capabilities.offering(self.source_offering_id).worst_case_availability_lag
            )
            or (
                offered.get("period_anchor_policy") == "fixed"
                and (
                    schedule.period_anchor is None
                    or schedule.period_anchor != aware_timestamp(str(offered.get("period_anchor")))
                )
            )
            or (
                offered.get("period_timezone_policy") == "fixed"
                and schedule.period_timezone != offered.get("period_timezone")
            )
        ):
            raise failure("BINDING_MISMATCH")

One public offering and the exact running components that implement it.

The wire model is copied into immutable bytes so mutating an adopter's Pydantic model after construction cannot change the advertised contract. Capability availability is still checked against live components.

Instance variables

var offering : ReportingDeliveryOffering
prop offering_id : str
Expand source code
@property
def offering_id(self) -> str:
    return str(self.wire()["offering_id"])
var producer : ReportingProducer
prop reconciled : bool
Expand source code
@property
def reconciled(self) -> bool:
    return bool(self.wire()["reconciliation_mode"] == "consumer_receipt")
var source_offering_id : str
var verification_key : ReportingVerificationKey

Methods

def check_configuration(self,
configuration: ReportingConfiguration,
binding: ReportingDestinationBinding,
*,
retention_days: int) ‑> None
Expand source code
def check_configuration(
    self,
    configuration: ReportingConfiguration,
    binding: ReportingDestinationBinding,
    *,
    retention_days: int,
) -> None:
    capabilities = self.check_source(effective=True)
    self.source_binding(configuration)
    self.configuration_schedule(configuration)
    raw, key = self.wire(), self.verification_key
    schedule, offered = configuration.schedule, raw["schedule"]
    if (
        binding.generation_key != configuration.generation_key
        or (
            configuration.report_definition_id,
            configuration.reporting_profile,
            configuration.feed_purpose,
            configuration.required_finality,
        )
        != (
            key.report_definition_id,
            key.reporting_profile,
            raw["feed_purpose"],
            raw["supported_finality"][0],
        )
        or not _same_definition(key, configuration.definition)
        or configuration.authoritative_party != "seller"
        or binding.reconciliation_mode != raw["reconciliation_mode"]
        or binding.feed_purpose != raw["feed_purpose"]
        or (binding.method, binding.transport, binding.format, binding.verification_profile)
        != (
            key.capability.method,
            key.capability.transport,
            key.capability.format,
            key.capability.verification_profile,
        )
        or binding.resource_retention_days != retention_days
        or binding.reader_compatibility != tuple(raw["method"].get("reader_compatibility", ()))
        or schedule.period_duration != offered["period_duration"]
        or iso_duration_to_timedelta(schedule.delivery_sla)
        != iso_duration_to_timedelta(offered["delivery_sla"])
        or iso_duration_milliseconds_v1(schedule.delivery_sla)
        < iso_duration_milliseconds_v1(
            capabilities.offering(self.source_offering_id).worst_case_availability_lag
        )
        or (
            offered.get("period_anchor_policy") == "fixed"
            and (
                schedule.period_anchor is None
                or schedule.period_anchor != aware_timestamp(str(offered.get("period_anchor")))
            )
        )
        or (
            offered.get("period_timezone_policy") == "fixed"
            and schedule.period_timezone != offered.get("period_timezone")
        )
    ):
        raise failure("BINDING_MISMATCH")
def check_source(self, *, effective: bool = False) ‑> ReportingSourceCapabilitiesV1
Expand source code
def check_source(self, *, effective: bool = False) -> ReportingSourceCapabilitiesV1:
    source = self.producer._source
    if (
        id(source) != self._source_identity
        or not isinstance(source, ReportingProductionSource)
        or id(self.producer._object_reader) != self._reader_identity
        or not isinstance(self.producer._object_reader, ReportingSourceStagedObjectReader)
    ):
        raise failure("BINDING_MISMATCH")
    capabilities = ReportingSourceCapabilitiesV1.model_validate(
        source.capabilities.model_dump(mode="json", exclude_none=True)
    )
    if effective and capabilities.scope != "effective_account":
        raise failure("BINDING_MISMATCH")
    raw = self.wire()
    source_offering = capabilities.offering(self.source_offering_id)
    contract, key = source_offering.contract, self.verification_key
    source_values = contract.model_dump(mode="json")
    expected = {
        "report_definition_id": key.report_definition_id,
        "reporting_profile": key.reporting_profile,
    }
    expected.update(
        {
            name: getattr(key.definition, name)
            for name in (
                "report_definition_uri",
                "report_definition_sha256",
                "schema_version",
                "schema_uri",
                "schema_sha256",
                "schema_dialect",
                "schema_ref_policy",
            )
        }
    )
    finality = raw["supported_finality"]
    configured = self.producer._offerings
    if (
        any(source_values.get(name) != value for name, value in expected.items())
        or source_offering.publication_namespace != configured.publication_namespace
        or dict(configured.source_scope) != capabilities.source_scope
        or not source_offering.provider_execution.supports_cancellation
        or (
            "official" in finality
            and (
                not isinstance(source_offering, AuthoritativeOfferingV1)
                or configured.official_offering_id != self.source_offering_id
                or (
                    self.reconciled
                    and source_offering.correction_policy != "immutable_correction"
                )
            )
        )
        or (
            "snapshot" in finality
            and (
                not isinstance(source_offering, ProvisionalSnapshotOfferingV1)
                or configured.snapshot_offering_id != self.source_offering_id
            )
        )
    ):
        raise failure("UNSUPPORTED_VERIFICATION")
    schedule = raw["schedule"]
    duration = iso_duration_milliseconds_v1(schedule["period_duration"])
    if not (
        iso_duration_milliseconds_v1(source_offering.windowing.minimum_window)
        <= duration
        <= iso_duration_milliseconds_v1(source_offering.windowing.maximum_window)
    ) or iso_duration_milliseconds_v1(schedule["delivery_sla"]) < iso_duration_milliseconds_v1(
        source_offering.worst_case_availability_lag
    ):
        raise failure("UNSUPPORTED_VERIFICATION")
    if isinstance(
        source_offering, ProvisionalSnapshotOfferingV1
    ) and duration < iso_duration_milliseconds_v1(source_offering.fastest_safe_cadence):
        raise failure("UNSUPPORTED_VERIFICATION")
    if (
        schedule["alignment"] == "source_timezone"
        and schedule.get("period_timezone") != source_offering.source_timezone
    ):
        raise failure("UNSUPPORTED_VERIFICATION")
    return capabilities
def configuration_schedule(self, configuration: ReportingConfiguration) ‑> dict[str, typing.Any]
Expand source code
def configuration_schedule(self, configuration: ReportingConfiguration) -> dict[str, Any]:
    """Project a proven legacy clock into the public schedule vocabulary.

    Existing captured clocks and their closed storage decoder stay intact.
    New production admission requires the normative public phase; an old
    explicit anchor is compatible only when it produces the same periods.
    Calendar-month/year clocks unsupported by that decoder are refused.
    """
    offered = self.wire()["schedule"]
    schedule = configuration.schedule
    alignment = offered["alignment"]
    expected_alignment = (
        alignment if alignment in {"utc", "account_timezone"} else "custom_timezone"
    )
    zone, duration, anchor = _schedule_clock(schedule, configuration.account_timezone)
    if (
        schedule.alignment != expected_alignment
        or schedule.period_duration != offered["period_duration"]
        or schedule.delivery_sla != offered["delivery_sla"]
        or (alignment != "billing_cycle" and (anchor - datetime(1970, 1, 1)) % duration)
        or (alignment == "billing_cycle" and schedule.period_anchor is None)
    ):
        raise failure("BINDING_MISMATCH")
    result: dict[str, Any] = {
        "period_duration": schedule.period_duration,
        "delivery_sla": schedule.delivery_sla,
        "alignment": alignment,
    }
    if alignment in {"source_timezone", "billing_cycle"}:
        result["period_timezone"] = zone.key
    if alignment == "billing_cycle":
        assert schedule.period_anchor is not None
        result["period_anchor"] = schedule.period_anchor.isoformat()
    if (
        offered.get("period_timezone_policy") == "fixed"
        or offered.get("period_anchor_policy") == "fixed"
    ) and result.get("period_timezone") != offered.get("period_timezone"):
        raise failure("BINDING_MISMATCH")
    if offered.get(
        "period_anchor_policy"
    ) == "fixed" and schedule.period_anchor != aware_timestamp(offered["period_anchor"]):
        raise failure("BINDING_MISMATCH")
    if (
        alignment == "source_timezone"
        and zone.key
        != self.check_source(effective=True).offering(self.source_offering_id).source_timezone
    ):
        raise failure("BINDING_MISMATCH")
    return result

Project a proven legacy clock into the public schedule vocabulary.

Existing captured clocks and their closed storage decoder stay intact. New production admission requires the normative public phase; an old explicit anchor is compatible only when it produces the same periods. Calendar-month/year clocks unsupported by that decoder are refused.

def source_binding(self, configuration: ReportingConfiguration) ‑> ReportingProductionSourceBinding
Expand source code
def source_binding(
    self, configuration: ReportingConfiguration
) -> ReportingProductionSourceBinding:
    require_account_work(configuration.account_id)
    try:
        capabilities = self.check_source(effective=True)
        source = self.producer._source
        assert isinstance(source, ReportingProductionSource)
        binding = source.configuration_binding(configuration)
        if binding is None:
            # Discovery can probe several generations before selecting a
            # dispatch. Refuse this candidate without revoking a turn that
            # may select another one; the producer's dispatch/publication
            # checks own the account-wide stop after a live denial.
            raise _SourceAuthorizationRevokedError()
        if type(binding) is not ReportingProductionSourceBinding:
            raise failure("BINDING_MISMATCH")
        binding.check(configuration, capabilities, self.source_offering_id)
        return binding
    except _SourceAuthorizationRevokedError:
        raise
    except Exception:
        raise failure("BINDING_MISMATCH") from None
def wire(self) ‑> dict[str, typing.Any]
Expand source code
def wire(self) -> dict[str, Any]:
    return dict(json.loads(self._wire))
class ReportingProductionProjection (*args, **kwargs)
Expand source code
@runtime_checkable
class ReportingProductionProjection(Protocol):
    """The v2 status projection a production store builds over itself."""

    ledger: Any
    outbox: Any
    escalation: ReportingDeliveryEscalation | None
    consumer_status_enabled: bool

    @property
    def policy(self) -> dict[str, Any]: ...

    async def rebuild_one(self) -> StatusTurn: ...

    async def sweep_one(self) -> StatusTurn: ...

    async def activate(self, *, account_id: str) -> bool: ...

The v2 status projection a production store builds over itself.

Ancestors

  • typing.Protocol
  • typing.Generic

Class variables

var consumer_status_enabled : bool
var escalation : ReportingDeliveryEscalation | None
var ledger : Any
var outbox : Any

Instance variables

prop policy : dict[str, Any]
Expand source code
@property
def policy(self) -> dict[str, Any]: ...

Methods

async def activate(self, *, account_id: str) ‑> bool
Expand source code
async def activate(self, *, account_id: str) -> bool: ...
async def rebuild_one(self) ‑> StatusTurn
Expand source code
async def rebuild_one(self) -> StatusTurn: ...
async def sweep_one(self) ‑> StatusTurn
Expand source code
async def sweep_one(self) -> StatusTurn: ...
class ReportingProductionSigning (resolver: ReportingSigningResolver,
algorithms: tuple[str, ...],
*,
brand_json_url: str)
Expand source code
@dataclass(frozen=True)
class ReportingProductionSigning:
    """A declared RFC 9421 algorithm contract checked on every resolved key.

    Key material remains in the trusted resolver. The public declaration and
    actual sender share this immutable contract; rotation cannot switch to an
    unadvertised algorithm or a legacy authentication path.
    """

    resolver: ReportingSigningResolver = field(repr=False)
    algorithms: tuple[str, ...]
    brand_json_url: str = field(kw_only=True)

    def __post_init__(self) -> None:
        object.__setattr__(self, "algorithms", tuple(self.algorithms))
        if (
            not self.algorithms
            or len(set(self.algorithms)) != len(self.algorithms)
            or not set(self.algorithms) <= ALLOWED_ALGS
            or not callable(getattr(self.resolver, "resolve", None))
        ):
            raise ReportingNotificationError("notification_signing_unready")
        try:
            if type(self.brand_json_url) is not str:
                raise ValueError
            identity = httpx.URL(self.brand_json_url)
            valid = (
                identity.scheme == "https"
                and bool(identity.host)
                and not identity.userinfo
                and not identity.query
                and not identity.fragment
                and identity.port in (None, 443)
            )
        except (TypeError, ValueError, httpx.InvalidURL):
            valid = False
        if not valid:
            raise ReportingNotificationError("notification_signing_unready")

    async def resolve(
        self, *, account_id: str, principal_id: str, signing_scope_id: str
    ) -> ReportingSigningMaterial:
        material = await self.resolver.resolve(
            account_id=account_id, principal_id=principal_id, signing_scope_id=signing_scope_id
        )
        if type(
            material
        ) is not ReportingSigningMaterial or material.advertised_algorithms != frozenset(
            self.algorithms
        ):
            raise ReportingNotificationError("notification_signing_unready")
        ReportingSigningMaterial.__post_init__(material)
        return material

    def wire(self) -> dict[str, Any]:
        return {
            "supported": True,
            "profile": "adcp/webhook-signing/v1",
            "algorithms": list(self.algorithms),
            "legacy_hmac_fallback": False,
            "delivery_retry_horizon_seconds": RETRY_HORIZON_SECONDS,
        }

A declared RFC 9421 algorithm contract checked on every resolved key.

Key material remains in the trusted resolver. The public declaration and actual sender share this immutable contract; rotation cannot switch to an unadvertised algorithm or a legacy authentication path.

Instance variables

var algorithms : tuple[str, ...]
var brand_json_url : str
var resolver : ReportingSigningResolver

Methods

async def resolve(self, *, account_id: str, principal_id: str, signing_scope_id: str) ‑> ReportingSigningMaterial
Expand source code
async def resolve(
    self, *, account_id: str, principal_id: str, signing_scope_id: str
) -> ReportingSigningMaterial:
    material = await self.resolver.resolve(
        account_id=account_id, principal_id=principal_id, signing_scope_id=signing_scope_id
    )
    if type(
        material
    ) is not ReportingSigningMaterial or material.advertised_algorithms != frozenset(
        self.algorithms
    ):
        raise ReportingNotificationError("notification_signing_unready")
    ReportingSigningMaterial.__post_init__(material)
    return material
def wire(self) ‑> dict[str, typing.Any]
Expand source code
def wire(self) -> dict[str, Any]:
    return {
        "supported": True,
        "profile": "adcp/webhook-signing/v1",
        "algorithms": list(self.algorithms),
        "legacy_hmac_fallback": False,
        "delivery_retry_horizon_seconds": RETRY_HORIZON_SECONDS,
    }
class ReportingProductionSource (*args, **kwargs)
Expand source code
@runtime_checkable
class ReportingProductionSource(ReportingSourceExecutor, Protocol):
    """A source with an authenticated generation mapping available before I/O.

    Discovery may precede any account binding. Admission and every source turn
    require the applicable binding, obtained from the source's trusted account
    configuration. The SDK calls ``configuration_binding`` immediately before
    dispatch and again under the account lock before sealing or publishing the
    result, including replay after a restart. Returning ``None`` discards that
    result without a success checkpoint and stops this account's remaining
    work for the turn. Restoring the binding permits work on the next turn.

    An in-flight fetch is allowed to finish: revocation takes effect at the next
    dispatch or publish. Adopters own any caching or latency inside their
    callback; the SDK does not retain an authorization grant.
    """

    def configuration_binding(
        self, configuration: ReportingConfiguration
    ) -> ReportingProductionSourceBinding | None:
        """Return the current trusted binding, or ``None`` to deny source work.

        Adopters own callback caching and latency. In-flight fetches finish;
        revocation takes effect at the next dispatch or publish.
        """
        raise NotImplementedError

A source with an authenticated generation mapping available before I/O.

Discovery may precede any account binding. Admission and every source turn require the applicable binding, obtained from the source's trusted account configuration. The SDK calls configuration_binding immediately before dispatch and again under the account lock before sealing or publishing the result, including replay after a restart. Returning None discards that result without a success checkpoint and stops this account's remaining work for the turn. Restoring the binding permits work on the next turn.

An in-flight fetch is allowed to finish: revocation takes effect at the next dispatch or publish. Adopters own any caching or latency inside their callback; the SDK does not retain an authorization grant.

Ancestors

Methods

def configuration_binding(self, configuration: ReportingConfiguration) ‑> ReportingProductionSourceBinding | None
Expand source code
def configuration_binding(
    self, configuration: ReportingConfiguration
) -> ReportingProductionSourceBinding | None:
    """Return the current trusted binding, or ``None`` to deny source work.

    Adopters own callback caching and latency. In-flight fetches finish;
    revocation takes effect at the next dispatch or publish.
    """
    raise NotImplementedError

Return the current trusted binding, or None to deny source work.

Adopters own callback caching and latency. In-flight fetches finish; revocation takes effect at the next dispatch or publish.

Inherited members

class ReportingProductionSourceBinding (generation_key: ReportingConfigurationGenerationKey,
capabilities_sha256: str,
media_buy_products: tuple[tuple[str, str], ...],
*,
configuration_sha256: str,
service_context: ReportingProductionSourceContext | None = None)
Expand source code
@dataclass(frozen=True)
class ReportingProductionSourceBinding:
    """Trusted account-to-source mapping, fixed for a configuration generation.

    ``media_buy_products`` comes from the authenticated source/account mapping,
    never from buyer JSON or a report-definition identifier. The SDK persists
    it with admission, checks the effective capability digest on every source
    turn, and refuses a changed mapping. Reauthorization can withdraw a binding;
    it cannot silently change historical scope. No credentials belong here.
    """

    generation_key: ReportingConfigurationGenerationKey
    capabilities_sha256: str
    media_buy_products: tuple[tuple[str, str], ...]
    configuration_sha256: str = field(kw_only=True)
    service_context: ReportingProductionSourceContext | None = field(
        default=None, kw_only=True, repr=False
    )

    def __post_init__(self) -> None:
        from adcp.reporting.evidence import reporting_identifier, sha256_value

        if type(self.generation_key) is not ReportingConfigurationGenerationKey:
            raise ValueError("source binding requires an exact configuration generation")
        sha256_value(self.capabilities_sha256)
        sha256_value(self.configuration_sha256)
        if (
            self.service_context is not None
            and type(self.service_context) is not ReportingProductionSourceContext
        ):
            raise ValueError("source binding requires an exact service source context")
        pairs = tuple(tuple(pair) for pair in self.media_buy_products)
        if any(len(pair) != 2 for pair in pairs):
            raise ValueError("source binding requires media-buy/product pairs")
        for media_buy_id, product_id in pairs:
            reporting_identifier(media_buy_id, maximum=255)
            reporting_identifier(product_id, maximum=255)
        if len({pair[0] for pair in pairs}) != len(pairs):
            raise ValueError("source binding media buys must be unique")
        object.__setattr__(self, "media_buy_products", tuple(sorted(pairs)))

    @classmethod
    def for_configuration(
        cls,
        configuration: ReportingConfiguration,
        *,
        capabilities_sha256: str,
        media_buy_products: tuple[tuple[str, str], ...],
    ) -> ReportingProductionSourceBinding:
        """Freeze the exact generation semantics and explicitly resolved products.

        Lifecycle changes retain the same semantic generation, matching the
        ledger's immutable configuration contract. Captured projection inputs
        independently retain each historical activation/deactivation boundary.
        """
        return cls(
            configuration.generation_key,
            capabilities_sha256,
            media_buy_products,
            configuration_sha256=hashlib.sha256(
                canonical_json_utf8_v1(_config_payload(configuration))
            ).hexdigest(),
        )

    def document(self) -> dict[str, Any]:
        key = self.generation_key
        document = {
            "account_id": key.account_id,
            "consumer_id": key.consumer_id,
            "delivery_config_id": key.delivery_config_id,
            "delivery_config_version": key.delivery_config_version,
            "capabilities_sha256": self.capabilities_sha256,
            "configuration_sha256": self.configuration_sha256,
            "media_buy_products": [list(pair) for pair in self.media_buy_products],
        }
        if self.service_context is not None:
            document["service_context"] = self.service_context.document()
            document["service_context_sha256"] = hashlib.sha256(
                self.service_context._wire
            ).hexdigest()
        return document

    def check(
        self,
        configuration: ReportingConfiguration,
        capabilities: ReportingSourceCapabilitiesV1,
        offering_id: str,
    ) -> None:
        offering = capabilities.offering(offering_id)
        if (
            self.generation_key != configuration.generation_key
            or self.configuration_sha256
            != hashlib.sha256(canonical_json_utf8_v1(_config_payload(configuration))).hexdigest()
            or capabilities.scope != "effective_account"
            or self.capabilities_sha256 != capabilities.capabilities_sha256
            or {pair[0] for pair in self.media_buy_products} != set(configuration.media_buy_ids)
            or (self.media_buy_products and "media_buy" not in offering.constituent_kinds)
            or any(pair[1] not in offering.product_ids for pair in self.media_buy_products)
        ):
            raise failure("BINDING_MISMATCH")

    def constituents(self) -> tuple[ReportingConstituent, ...]:
        return tuple(
            MediaBuyConstituentV1(
                constituent_id=media_buy_id, media_buy_id=media_buy_id, product_id=product_id
            )
            for media_buy_id, product_id in self.media_buy_products
        )

Trusted account-to-source mapping, fixed for a configuration generation.

media_buy_products comes from the authenticated source/account mapping, never from buyer JSON or a report-definition identifier. The SDK persists it with admission, checks the effective capability digest on every source turn, and refuses a changed mapping. Reauthorization can withdraw a binding; it cannot silently change historical scope. No credentials belong here.

Static methods

def for_configuration(configuration: ReportingConfiguration,
*,
capabilities_sha256: str,
media_buy_products: tuple[tuple[str, str], ...]) ‑> ReportingProductionSourceBinding

Freeze the exact generation semantics and explicitly resolved products.

Lifecycle changes retain the same semantic generation, matching the ledger's immutable configuration contract. Captured projection inputs independently retain each historical activation/deactivation boundary.

Instance variables

var capabilities_sha256 : str
var configuration_sha256 : str
var generation_key : ReportingConfigurationGenerationKey
var media_buy_products : tuple[tuple[str, str], ...]
var service_context : ReportingProductionSourceContext | None

Methods

def check(self,
configuration: ReportingConfiguration,
capabilities: ReportingSourceCapabilitiesV1,
offering_id: str) ‑> None
Expand source code
def check(
    self,
    configuration: ReportingConfiguration,
    capabilities: ReportingSourceCapabilitiesV1,
    offering_id: str,
) -> None:
    offering = capabilities.offering(offering_id)
    if (
        self.generation_key != configuration.generation_key
        or self.configuration_sha256
        != hashlib.sha256(canonical_json_utf8_v1(_config_payload(configuration))).hexdigest()
        or capabilities.scope != "effective_account"
        or self.capabilities_sha256 != capabilities.capabilities_sha256
        or {pair[0] for pair in self.media_buy_products} != set(configuration.media_buy_ids)
        or (self.media_buy_products and "media_buy" not in offering.constituent_kinds)
        or any(pair[1] not in offering.product_ids for pair in self.media_buy_products)
    ):
        raise failure("BINDING_MISMATCH")
def constituents(self) ‑> tuple[ProductConstituentV1 | PackageItemConstituentV1 | MediaBuyConstituentV1, ...]
Expand source code
def constituents(self) -> tuple[ReportingConstituent, ...]:
    return tuple(
        MediaBuyConstituentV1(
            constituent_id=media_buy_id, media_buy_id=media_buy_id, product_id=product_id
        )
        for media_buy_id, product_id in self.media_buy_products
    )
def document(self) ‑> dict[str, typing.Any]
Expand source code
def document(self) -> dict[str, Any]:
    key = self.generation_key
    document = {
        "account_id": key.account_id,
        "consumer_id": key.consumer_id,
        "delivery_config_id": key.delivery_config_id,
        "delivery_config_version": key.delivery_config_version,
        "capabilities_sha256": self.capabilities_sha256,
        "configuration_sha256": self.configuration_sha256,
        "media_buy_products": [list(pair) for pair in self.media_buy_products],
    }
    if self.service_context is not None:
        document["service_context"] = self.service_context.document()
        document["service_context_sha256"] = hashlib.sha256(
            self.service_context._wire
        ).hexdigest()
    return document
class ReportingProductionSourceRegistry (*, account_context: ReportingContextResolver)
Expand source code
class ReportingProductionSourceRegistry:
    """Bind stable adapter names to the actual fixed production producers.

    ``account_context`` runs only at authenticated configuration admission,
    outside the storage transaction. Recovery validates the selected persisted
    generation against these profiles and the live production source binding;
    it never calls the resolver or rebuilds an in-memory account catalog.
    """

    def __init__(self, *, account_context: ReportingContextResolver) -> None:
        self._resolve = account_context
        self._entries: dict[str, _Registration] = {}
        self._frozen = False

    def register(self, adapter: str, producer: ReportingProducer) -> None:
        if self._frozen:
            raise ValueError("production source registry is frozen")
        if not re.fullmatch(r"[A-Za-z0-9_.:-]{1,128}", adapter):
            raise ValueError("adapter must be a stable identifier")
        if adapter in self._entries or any(v.producer is producer for v in self._entries.values()):
            raise ValueError("production source profile must have one unambiguous registration")
        self._entries[adapter] = _Registration(
            adapter, producer, canonical_json_utf8_v1(_profile(producer._offerings))
        )

    def freeze(self, offerings: tuple[ReportingProductionOffering, ...]) -> None:
        for offering in offerings:
            self._registration(offering)
        if any(
            not any(entry.producer is offering.producer for offering in offerings)
            for entry in self._entries.values()
        ):
            raise ValueError("registered production source profile has no offering")
        self._frozen = True

    def _registration(self, offering: ReportingProductionOffering) -> _Registration:
        matches = [v for v in self._entries.values() if v.producer is offering.producer]
        if len(matches) != 1:
            raise ValueError("production source profile is not registered")
        entry = matches[0]
        if entry.profile != canonical_json_utf8_v1(_profile(entry.producer._offerings)):
            raise ValueError("production source profile changed")
        return entry

    def _expected(
        self,
        configuration: ReportingConfiguration,
        offering: ReportingProductionOffering,
        capabilities: ReportingSourceCapabilitiesV1,
    ) -> dict[str, Any]:
        entry = self._registration(offering)
        return {
            "version": 1,
            "adapter": entry.adapter,
            "account_id": configuration.account_id,
            "account_timezone": configuration.account_timezone,
            "offering_id": offering.offering_id,
            "source_offering_id": offering.source_offering_id,
            "capabilities_sha256": capabilities.capabilities_sha256,
            **json.loads(entry.profile),
        }

    async def resolve(
        self,
        configuration: ReportingConfiguration,
        offering: ReportingProductionOffering,
        capabilities: ReportingSourceCapabilitiesV1,
    ) -> ReportingProductionSourceContext:
        from adcp.reporting.service import ReportingAccountContext, _thaw

        context = self._resolve(configuration)
        if inspect.isawaitable(context):
            context = await context
        expected = self._expected(configuration, offering, capabilities)
        if (
            type(context) is not ReportingAccountContext
            or context.account_id != configuration.account_id
            or context.account_timezone != configuration.account_timezone
            or context.adapter != expected["adapter"]
            or canonical_json_utf8_v1(_profile(context.producer_offerings()))
            != self._registration(offering).profile
            or (
                context.capability_offering
                and canonical_json_utf8_v1(_thaw(context.capability_offering))
                != canonical_json_utf8_v1(offering.wire())
            )
        ):
            raise ValueError("resolved account context does not match its fixed production profile")
        return ReportingProductionSourceContext(canonical_json_utf8_v1(expected))

    def recover(
        self,
        configuration: ReportingConfiguration,
        offering: ReportingProductionOffering,
        capabilities: ReportingSourceCapabilitiesV1,
        document: dict[str, Any] | None,
    ) -> ReportingProductionSourceContext:
        if document is None:
            raise ValueError("legacy service source context requires explicit migration")
        expected = canonical_json_utf8_v1(self._expected(configuration, offering, capabilities))
        if expected != canonical_json_utf8_v1(document):
            raise ValueError(
                "persisted account context does not match its fixed production profile"
            )
        return ReportingProductionSourceContext(expected)

Bind stable adapter names to the actual fixed production producers.

account_context runs only at authenticated configuration admission, outside the storage transaction. Recovery validates the selected persisted generation against these profiles and the live production source binding; it never calls the resolver or rebuilds an in-memory account catalog.

Methods

def freeze(self,
offerings: tuple[ReportingProductionOffering, ...]) ‑> None
Expand source code
def freeze(self, offerings: tuple[ReportingProductionOffering, ...]) -> None:
    for offering in offerings:
        self._registration(offering)
    if any(
        not any(entry.producer is offering.producer for offering in offerings)
        for entry in self._entries.values()
    ):
        raise ValueError("registered production source profile has no offering")
    self._frozen = True
def recover(self,
configuration: ReportingConfiguration,
offering: ReportingProductionOffering,
capabilities: ReportingSourceCapabilitiesV1,
document: dict[str, Any] | None) ‑> ReportingProductionSourceContext
Expand source code
def recover(
    self,
    configuration: ReportingConfiguration,
    offering: ReportingProductionOffering,
    capabilities: ReportingSourceCapabilitiesV1,
    document: dict[str, Any] | None,
) -> ReportingProductionSourceContext:
    if document is None:
        raise ValueError("legacy service source context requires explicit migration")
    expected = canonical_json_utf8_v1(self._expected(configuration, offering, capabilities))
    if expected != canonical_json_utf8_v1(document):
        raise ValueError(
            "persisted account context does not match its fixed production profile"
        )
    return ReportingProductionSourceContext(expected)
def register(self, adapter: str, producer: ReportingProducer) ‑> None
Expand source code
def register(self, adapter: str, producer: ReportingProducer) -> None:
    if self._frozen:
        raise ValueError("production source registry is frozen")
    if not re.fullmatch(r"[A-Za-z0-9_.:-]{1,128}", adapter):
        raise ValueError("adapter must be a stable identifier")
    if adapter in self._entries or any(v.producer is producer for v in self._entries.values()):
        raise ValueError("production source profile must have one unambiguous registration")
    self._entries[adapter] = _Registration(
        adapter, producer, canonical_json_utf8_v1(_profile(producer._offerings))
    )
async def resolve(self,
configuration: ReportingConfiguration,
offering: ReportingProductionOffering,
capabilities: ReportingSourceCapabilitiesV1) ‑> ReportingProductionSourceContext
Expand source code
async def resolve(
    self,
    configuration: ReportingConfiguration,
    offering: ReportingProductionOffering,
    capabilities: ReportingSourceCapabilitiesV1,
) -> ReportingProductionSourceContext:
    from adcp.reporting.service import ReportingAccountContext, _thaw

    context = self._resolve(configuration)
    if inspect.isawaitable(context):
        context = await context
    expected = self._expected(configuration, offering, capabilities)
    if (
        type(context) is not ReportingAccountContext
        or context.account_id != configuration.account_id
        or context.account_timezone != configuration.account_timezone
        or context.adapter != expected["adapter"]
        or canonical_json_utf8_v1(_profile(context.producer_offerings()))
        != self._registration(offering).profile
        or (
            context.capability_offering
            and canonical_json_utf8_v1(_thaw(context.capability_offering))
            != canonical_json_utf8_v1(offering.wire())
        )
    ):
        raise ValueError("resolved account context does not match its fixed production profile")
    return ReportingProductionSourceContext(canonical_json_utf8_v1(expected))
class ReportingProductionStore (*args, **kwargs)
Expand source code
@runtime_checkable
class ReportingProductionStore(
    ReportingLedgerStore,
    ReportingReconciliationStore,
    ReportingMaterializerStore,
    ReportingReceiptBatchStore,
    ReportingFeedStore,
    Protocol,
):
    """A ledger that can carry the production composition.

    It is a Core ledger, a reconciliation store, a materializer store, a
    receipt-batch store and a frozen feed store at once, plus the composition
    hooks below.
    """

    #: Set by :class:`ReportingProductionSupport` when it takes ownership of the store.
    production_support: weakref.ReferenceType[ReportingProductionSupport] | None
    #: Set by the status projection; the composition checks it matches its policy.
    projection_read_policy: dict[str, Any]

    @property
    def durable(self) -> bool:
        """Whether storage survives the process. Only durable stores advertise production."""
        ...

    @property
    def clock(self) -> Callable[[], datetime] | None:
        """The explicit clock override, or ``None`` for the store's own time source."""
        ...

    @property
    def storage_identity(self) -> object:
        """The resource shared by every participant (a pool, or the store itself)."""
        ...

    @property
    def storage_open(self) -> bool:
        """Whether that resource still accepts work."""
        ...

    def is_sdk_production_store(self) -> bool:
        """Exactly a shipped production store, not a subclass."""
        ...

    def status_projection(
        self,
        *,
        consumer_status_enabled: bool,
        escalation: ReportingDeliveryEscalation | None,
        revision_ownership: bool,
    ) -> ReportingProductionProjection: ...

    def is_sdk_status_projection(self, projection: object) -> bool:
        """Exactly the shipped projection class for this store."""
        ...

    def projection_linked(self, projection: ReportingProductionProjection) -> bool:
        """Whether the projection's queue shares this store's storage."""
        ...

    def production_outboxes(
        self, projection: ReportingProductionProjection
    ) -> tuple[Any, Any, Any]:
        """The core, status and readiness queues, in that order."""
        ...

    def notification_workers_linked(self, workers: Sequence[ReportingNotificationWorker]) -> bool:
        """Whether every worker drives this store's exact queue classes over its storage."""
        ...

    async def validate_production_schema(
        self, *, notifications: bool, service_context: bool
    ) -> None:
        """Raise ``reporting_production_schema_unready`` unless the catalog is installed."""
        ...

    async def read_delivery_window(
        self, key: tuple[str, str], *, now: datetime
    ) -> tuple[SavedDeliveryWindow | None, datetime]:
        """The recorded window for ``(account_id, idempotency_key)`` and the store's instant."""
        ...

    async def reserve_delivery_attempt(
        self,
        activity: ReportingActivityStore,
        lease: DeliveryLease,
        *,
        request: ActivityRequest,
        now: datetime,
        queue: str,
        expected: tuple[str, str],
        horizon_seconds: int,
    ) -> tuple[WebhookAttempt | None, datetime | None, bool]:
        """Reserve one HTTP attempt and its immutable first-attempt deadline atomically."""
        ...

    def maintenance_operations(self) -> tuple[MaintenanceOperation, ...]:
        """Retention passes for the features this store opted into, in run order."""
        ...

    async def activate_production(self, *, account_id: str) -> bool: ...

    async def admit_production_configuration(
        self,
        configuration: ReportingConfiguration,
        binding: ReportingDestinationBinding,
        *,
        offering_id: str,
        service_context: ReportingProductionSourceContext | None = None,
    ) -> None: ...

A ledger that can carry the production composition.

It is a Core ledger, a reconciliation store, a materializer store, a receipt-batch store and a frozen feed store at once, plus the composition hooks below.

Ancestors

Class variables

var production_support : weakref.ReferenceType[ReportingProductionSupport] | None

Set by :class:ReportingProductionSupport when it takes ownership of the store.

var projection_read_policy : dict[str, Any]

Set by the status projection; the composition checks it matches its policy.

Instance variables

prop clock : Callable[[], datetime] | None
Expand source code
@property
def clock(self) -> Callable[[], datetime] | None:
    """The explicit clock override, or ``None`` for the store's own time source."""
    ...

The explicit clock override, or None for the store's own time source.

prop durable : bool
Expand source code
@property
def durable(self) -> bool:
    """Whether storage survives the process. Only durable stores advertise production."""
    ...

Whether storage survives the process. Only durable stores advertise production.

prop storage_identity : object
Expand source code
@property
def storage_identity(self) -> object:
    """The resource shared by every participant (a pool, or the store itself)."""
    ...

The resource shared by every participant (a pool, or the store itself).

prop storage_open : bool
Expand source code
@property
def storage_open(self) -> bool:
    """Whether that resource still accepts work."""
    ...

Whether that resource still accepts work.

Methods

async def activate_production(self, *, account_id: str) ‑> bool
Expand source code
async def activate_production(self, *, account_id: str) -> bool: ...
async def admit_production_configuration(self,
configuration: ReportingConfiguration,
binding: ReportingDestinationBinding,
*,
offering_id: str,
service_context: ReportingProductionSourceContext | None = None) ‑> None
Expand source code
async def admit_production_configuration(
    self,
    configuration: ReportingConfiguration,
    binding: ReportingDestinationBinding,
    *,
    offering_id: str,
    service_context: ReportingProductionSourceContext | None = None,
) -> None: ...
def is_sdk_production_store(self) ‑> bool
Expand source code
def is_sdk_production_store(self) -> bool:
    """Exactly a shipped production store, not a subclass."""
    ...

Exactly a shipped production store, not a subclass.

def is_sdk_status_projection(self, projection: object) ‑> bool
Expand source code
def is_sdk_status_projection(self, projection: object) -> bool:
    """Exactly the shipped projection class for this store."""
    ...

Exactly the shipped projection class for this store.

def maintenance_operations(self) ‑> tuple[tuple[str, Callable[[], Awaitable[typing.Any]]], ...]
Expand source code
def maintenance_operations(self) -> tuple[MaintenanceOperation, ...]:
    """Retention passes for the features this store opted into, in run order."""
    ...

Retention passes for the features this store opted into, in run order.

def notification_workers_linked(self, workers: Sequence[ReportingNotificationWorker]) ‑> bool
Expand source code
def notification_workers_linked(self, workers: Sequence[ReportingNotificationWorker]) -> bool:
    """Whether every worker drives this store's exact queue classes over its storage."""
    ...

Whether every worker drives this store's exact queue classes over its storage.

def production_outboxes(self,
projection: ReportingProductionProjection) ‑> tuple[typing.Any, typing.Any, typing.Any]
Expand source code
def production_outboxes(
    self, projection: ReportingProductionProjection
) -> tuple[Any, Any, Any]:
    """The core, status and readiness queues, in that order."""
    ...

The core, status and readiness queues, in that order.

def projection_linked(self,
projection: ReportingProductionProjection) ‑> bool
Expand source code
def projection_linked(self, projection: ReportingProductionProjection) -> bool:
    """Whether the projection's queue shares this store's storage."""
    ...

Whether the projection's queue shares this store's storage.

async def read_delivery_window(self, key: tuple[str, str], *, now: datetime) ‑> tuple[tuple[str, str, datetime.datetime, datetime.datetime] | None, datetime.datetime]
Expand source code
async def read_delivery_window(
    self, key: tuple[str, str], *, now: datetime
) -> tuple[SavedDeliveryWindow | None, datetime]:
    """The recorded window for ``(account_id, idempotency_key)`` and the store's instant."""
    ...

The recorded window for (account_id, idempotency_key) and the store's instant.

async def reserve_delivery_attempt(self,
activity: ReportingActivityStore,
lease: DeliveryLease,
*,
request: ActivityRequest,
now: datetime,
queue: str,
expected: tuple[str, str],
horizon_seconds: int) ‑> tuple[WebhookAttempt | None, datetime | None, bool]
Expand source code
async def reserve_delivery_attempt(
    self,
    activity: ReportingActivityStore,
    lease: DeliveryLease,
    *,
    request: ActivityRequest,
    now: datetime,
    queue: str,
    expected: tuple[str, str],
    horizon_seconds: int,
) -> tuple[WebhookAttempt | None, datetime | None, bool]:
    """Reserve one HTTP attempt and its immutable first-attempt deadline atomically."""
    ...

Reserve one HTTP attempt and its immutable first-attempt deadline atomically.

def status_projection(self,
*,
consumer_status_enabled: bool,
escalation: ReportingDeliveryEscalation | None,
revision_ownership: bool) ‑> ReportingProductionProjection
Expand source code
def status_projection(
    self,
    *,
    consumer_status_enabled: bool,
    escalation: ReportingDeliveryEscalation | None,
    revision_ownership: bool,
) -> ReportingProductionProjection: ...
async def validate_production_schema(self, *, notifications: bool, service_context: bool) ‑> None
Expand source code
async def validate_production_schema(
    self, *, notifications: bool, service_context: bool
) -> None:
    """Raise ``reporting_production_schema_unready`` unless the catalog is installed."""
    ...

Raise reporting_production_schema_unready unless the catalog is installed.

Inherited members

class ReportingProductionSupport (materializer: ReportingMaterializerService,
projection: ReportingProductionProjection,
*,
offerings: tuple[ReportingProductionOffering, ...],
configuration_task: ReportingProductionConfigurationTask,
resolve_account: ReceiptAccountResolver,
buyer_agents: BuyerAgentRegistry | None = None,
automated_recovery_window: timedelta = datetime.timedelta(seconds=21600),
status_retention_days: int = 400,
notification_workers: tuple[ReportingNotificationWorker, ...] = (),
poll_seconds: float = 0.25,
adcp_version: str | None = None,
source_registry: ReportingProductionSourceRegistry | None = None,
maintenance_seconds: float | None = 300.0)
Expand source code
class ReportingProductionSupport:
    """Compose, mount, start, then activate accounts after draining old workers.

    The owned worker performs indexed producer/materializer/projector turns.
    Stopping it prevents fresh admission while registered discovery remains stable. An
    optional HTTP notification worker is independent of polling readiness;
    enabled logical enqueue is always part of the materializer transaction.

    Migrate with ``store.create_schema()`` before construction/start. For DDL,
    drain and close this support, migrate, and construct fresh support. Schema
    proofs do not detect arbitrary serving-time DDL or search-path changes.
    """

    def __init__(
        self,
        materializer: ReportingMaterializerService,
        projection: ReportingProductionProjection,
        *,
        offerings: tuple[ReportingProductionOffering, ...],
        configuration_task: ReportingProductionConfigurationTask,
        resolve_account: ReceiptAccountResolver,
        buyer_agents: BuyerAgentRegistry | None = None,
        automated_recovery_window: timedelta = timedelta(hours=6),
        status_retention_days: int = 400,
        notification_workers: tuple[ReportingNotificationWorker, ...] = (),
        poll_seconds: float = 0.25,
        adcp_version: str | None = None,
        source_registry: ReportingProductionSourceRegistry | None = None,
        maintenance_seconds: float | None = 300.0,
    ) -> None:
        from adcp.reporting.outbox.worker import ReportingNotificationWorker
        from adcp.reporting.production.handler import ReportingProductionHandler

        store = materializer.store
        if (
            type(materializer) is not ReportingMaterializerService
            or not isinstance(store, ReportingProductionStore)
            or not store.is_sdk_production_store()
            or not store.is_sdk_status_projection(projection)
            or projection.ledger is not store
            or type(configuration_task) is not ReportingProductionConfigurationTask
            or type(offerings) is not tuple
            or not offerings
            or any(type(o) is not ReportingProductionOffering for o in offerings)
            or len({o.offering_id for o in offerings}) != len(offerings)
            or type(status_retention_days) is not int
            or not 1 <= status_retention_days <= 36500
            or automated_recovery_window <= timedelta(0)
            or not 0.01 <= poll_seconds <= 60
            or (maintenance_seconds is not None and not 0.01 <= maintenance_seconds <= 86_400)
            or type(notification_workers) is not tuple
            or any(type(w) is not ReportingNotificationWorker for w in notification_workers)
        ):
            raise ValueError(
                "production support requires exact SDK components and bounded promises"
            )
        assert isinstance(store, ReportingProductionStore)
        self.store: ReportingProductionStore = store
        previous = self.store.production_support
        if previous is not None and previous() is not None:
            raise ReportingNotificationError("reporting_production_owner_conflict")
        self.materializer, self.projection = materializer, projection
        self.offerings, self.configuration_task = offerings, configuration_task
        if source_registry is not None:
            if type(source_registry) is not ReportingProductionSourceRegistry:
                raise ValueError("production requires an exact source registry")
            source_registry.freeze(offerings)
        self.source_registry = source_registry
        self._service_lifecycle: _ServiceLifecycle | None = None
        self.automated_recovery_window, self.status_retention_days = (
            automated_recovery_window,
            status_retention_days,
        )
        self.notification_workers, self.poll_seconds = notification_workers, poll_seconds
        self.maintenance_seconds = maintenance_seconds
        self._next_maintenance = 0.0
        #: The last pass's integer counters per operation, for health checks and dashboards.
        self.maintenance_report: dict[str, dict[str, int]] = {}
        from adcp.reporting.production.notifications import worker_identity

        self._notification_identity = tuple(worker_identity(w) for w in notification_workers)
        self.handler = ReportingProductionHandler(
            self,
            resolve_account=resolve_account,
            buyer_agents=buyer_agents,
            adcp_version=adcp_version,
        )
        self._mounts: list[_MountedProduction] = []
        self._task: asyncio.Task[None] | None = None
        self._notification_task: asyncio.Task[None] | None = None
        self._stop = asyncio.Event()
        self._started = asyncio.Event()
        self._notification_started = asyncio.Event()
        self._closed = False
        self._failed = False
        self._producer_turn: ContextVar[ReportingProducer | None] = ContextVar(
            "reporting_production_source_turn", default=None
        )
        self._schema_task: asyncio.Task[bool] | None = None
        self._schema_epoch = 0
        self._schema_positive: tuple[int, int] | None = None
        self._protocol_version = self.handler.get_adcp_version()
        self._components = self._component_ids()
        self._methods = self._handler_methods()
        self.store.production_support = weakref.ref(self)
        self._assert_components(running=False, mounted=False)
        from adcp.reporting.production._declaration import declared_reporting_delivery
        from adcp.reporting.production.notifications import signing_capabilities, signing_identity

        writer = self.materializer.writer
        assert isinstance(writer, ReportingProductionDestination)
        declaration: dict[str, Any] = {
            "reporting_delivery": declared_reporting_delivery(
                offerings=[o.wire() for o in self.offerings],
                destination=writer,
                durable=self.store.durable,
                escalation=self.projection.escalation or ReportingDeliveryEscalation(),
                consumer_status_enabled=self.projection.consumer_status_enabled,
                automated_recovery_window=self.automated_recovery_window,
                status_retention_days=self.status_retention_days,
                notifications=bool(self.notification_workers),
            )
        }
        if self.notification_workers and declaration["reporting_delivery"]:
            declaration["webhook_signing"] = signing_capabilities(self)
            declaration["identity"] = signing_identity(self)
        self._declaration = json.dumps(declaration)

    def _declared_capabilities(self) -> dict[str, Any]:
        """Detached promises captured when the concrete graph was registered."""
        # Worker state does not change registered promises. A changed protocol
        # pin invalidates the declaration itself, even with a warm schema proof.
        if (
            self.handler._adcp_version != self._protocol_version
            or self.handler.get_adcp_version() != self._protocol_version
        ):
            return {"reporting_delivery": {}}
        return dict(json.loads(self._declaration))

    @property
    def keys(self) -> tuple[ReportingVerificationKey, ...]:
        return tuple(dict.fromkeys(o.verification_key for o in self.offerings))

    @property
    def notifications_enabled(self) -> bool:
        return bool(self.projection.policy["notifications_enabled"])

    def _component_ids(self) -> tuple[int, ...]:
        return tuple(
            id(v)
            for v in (
                self.store,
                self.store.storage_identity,
                self.materializer,
                self.materializer.io,
                self.materializer.io.registry,
                self.materializer.io.resolver,
                self.materializer.writer,
                self.projection,
                self.projection.outbox,
                self.configuration_task,
                self.source_registry,
                *self.offerings,
                *self.notification_workers,
            )
        )

    def _handler_methods(self) -> tuple[object, ...]:
        return tuple(
            getattr(getattr(self.handler, name), "__func__", None)
            for name in (
                "get_reporting_status",
                "get_media_buy_delivery",
                "sync_reporting_receipts",
                "sync_reporting_status",
                "sync_accounts",
                "get_adcp_capabilities",
                "get_adcp_version",
            )
        )

    def _mounted(self, *, receipts: bool = False) -> bool:
        required = {
            "get_adcp_capabilities",
            "get_reporting_status",
            "get_media_buy_delivery",
            "sync_accounts",
        }
        if receipts:
            required.add("sync_reporting_receipts")
        if self.projection.consumer_status_enabled:
            required.add("sync_reporting_status")
        live = [proof for proof in self._mounts if proof.mount() is not None]
        return bool(live) and all(
            required <= proof.entries.keys()
            and all(proof.current().get(name) == proof.entries[name] for name in required)
            for proof in live
        )

    def _assert_components(self, *, running: bool = True, mounted: bool = True) -> None:
        from adcp.reporting.production.notifications import check_workers

        check_workers(self)
        writer = self.materializer.writer
        if (
            self._closed
            or self._failed
            or (running and (self._task is None or self._task.done()))
            or (
                running
                and self.notification_workers
                and (self._notification_task is None or self._notification_task.done())
            )
            or self._components != self._component_ids()
            or self._methods != self._handler_methods()
            or type(self.handler._adcp_version) is not str
            or self.handler._adcp_version != self._protocol_version
            or ((running or mounted) and not self.store.storage_open)
            or self.materializer.store is not self.store
            or self.projection.ledger is not self.store
            or not self.store.projection_linked(self.projection)
            or self.handler.receipt_store is not self.store
            or self.handler.reporting_feed_store is not self.store
            or self.handler._feed_consumer_status_enabled != self.projection.consumer_status_enabled
            or self.store.projection_read_policy != self.projection.policy
            or type(self.materializer.io) is not ReportingDestinationIO
            or isinstance(writer, ReferenceReportingDestinationWriter)
            or isinstance(self.materializer.io.resolver, ReferenceReportingResolver)
            or not isinstance(writer, ReportingProductionDestination)
            or writer is not self.materializer.io.resolver
            or writer.production_eligible is not True
            or type(writer.resource_retention_days) is not int
            or not 1 <= writer.resource_retention_days <= 36500
            or type(writer.authorization_revocation_seconds) is not int
            or not 0 <= writer.authorization_revocation_seconds <= 86400
            or (mounted and not self._mounted())
        ):
            raise ReportingNotificationError("reporting_production_component_unready")

    def _offering_ready(self, offering: ReportingProductionOffering) -> bool:
        try:
            if (
                offering.producer.store is not self.store
                or type(offering.producer._max_periods_per_turn) is not int
                or not 1 <= offering.producer._max_periods_per_turn <= 64
                or offering.producer.escalation != self.projection.escalation
                or not _method_ready(self.materializer.writer, offering)
                or (offering.reconciled and not self._mounted(receipts=True))
            ):
                return False
            verifier = self.materializer.io.registry.require(offering.verification_key)
            profile = offering.wire()["reporting_profile"]
            contract = json.loads(verifier.canonicalization_bytes)
            definition = json.loads(verifier.definition_bytes)
            if (
                offering.producer._revision_verifier is not verifier
                or profile["primary_keys"] != contract["primary_keys"]
                or profile["grain"] != definition.get("grain")
            ):
                return False
            offering.check_source()
            if self.source_registry is not None:
                self.source_registry._registration(offering)
            return True
        except Exception:
            return False

    def _admission_policy(self) -> dict[str, Any]:
        self._assert_components()
        # This fixes the installed contract, not its current authorization.
        # Each reservation separately proves its own offering; an unrelated
        # provider outage must not rewrite this epoch or veto healthy offerings.
        ready = self.offerings
        return {
            "version": 2,
            "verification_keys": sorted({verification_key_id(o.verification_key) for o in ready}),
            "offerings": sorted(hashlib.sha256(o._wire).hexdigest() for o in ready),
            "producers": sorted(o._producer_key for o in ready),
            "notifications_enabled": self.notifications_enabled,
            "projection": self.projection.policy,
        }

    def _configuration_offering(
        self,
        configuration: ReportingConfiguration,
        binding: ReportingDestinationBinding,
        *,
        offering_id: str | None = None,
        producer_key: str | None = None,
    ) -> ReportingProductionOffering:
        self._assert_components()
        writer = self.materializer.writer
        assert isinstance(writer, ReportingProductionDestination)
        matches = []
        for offering in self.offerings:
            if (offering_id is not None and offering.offering_id != offering_id) or (
                producer_key is not None and offering._producer_key != producer_key
            ):
                continue
            if not self._offering_ready(offering):
                continue
            try:
                offering.check_configuration(
                    configuration, binding, retention_days=writer.resource_retention_days
                )
                self._destination_binding(binding, offering)
            # A failed proof never qualifies this offering.
            except Exception:  # nosec B112
                continue
            matches.append(offering)
        if (
            len(matches) != 1
            or configuration.automated_recovery_window != self.automated_recovery_window
            or configuration.status_retention_days < self.status_retention_days
        ):
            raise failure("BINDING_MISMATCH")
        return matches[0]

    def _destination_binding(
        self, binding: ReportingDestinationBinding, offering: ReportingProductionOffering
    ) -> ReportingProductionDestinationBinding:
        try:
            writer = self.materializer.writer
            assert isinstance(writer, ReportingProductionDestination)
            resolved = writer.configuration_binding(binding)
            if (
                type(resolved) is not ReportingProductionDestinationBinding
                or resolved.binding != binding
                or resolved.method.capability != offering.verification_key.capability
                or resolved.method.wire() != offering.wire()["method"]
            ):
                raise failure("BINDING_MISMATCH")
            return resolved
        except Exception:
            raise failure("BINDING_MISMATCH") from None

    def _producer_keys(self) -> tuple[str, ...]:
        self._assert_components()
        producer = self._producer_turn.get()
        return tuple(
            o._producer_key
            for o in self.offerings
            if o.producer is producer and self._offering_ready(o)
        )

    def validate_configuration(self, value: ReportingConfigurationAdmission) -> None:
        value.check(self)

    def _source_binding(
        self,
        configuration: ReportingConfiguration,
        producer_key: str,
        *,
        document: dict[str, Any] | None = None,
        service_context: ReportingProductionSourceContext | None = None,
    ) -> ReportingProductionSourceBinding:
        self._assert_components()
        matches = [
            offering
            for offering in self.offerings
            if offering._producer_key == producer_key and self._offering_ready(offering)
        ]
        if len(matches) != 1:
            raise failure("BINDING_MISMATCH")
        offering = matches[0]
        binding = offering.source_binding(configuration)
        if self.source_registry is not None:
            context = self.source_registry.recover(
                configuration,
                offering,
                offering.check_source(effective=True),
                (
                    service_context.document()
                    if service_context is not None
                    else (document or {}).get("service_context")
                ),
            )
            binding = replace(binding, service_context=context)
        elif service_context is not None or (document or {}).get("service_context") is not None:
            raise failure("BINDING_MISMATCH")
        return binding

    async def _admit_configuration(self, value: ReportingConfigurationAdmission) -> None:
        context = None
        if self.source_registry is not None:
            offering = self._configuration_offering(
                value.configuration, value.binding, offering_id=value.offering_id
            )
            context = await self.source_registry.resolve(
                value.configuration, offering, offering.check_source(effective=True)
            )
        await self.store.admit_production_configuration(
            value.configuration,
            value.binding,
            offering_id=value.offering_id,
            service_context=context,
        )

    def _check_source_binding(
        self,
        configuration: ReportingConfiguration,
        producer_key: str,
        document: dict[str, Any] | None,
    ) -> ReportingProductionSourceBinding:
        try:
            binding = self._source_binding(configuration, producer_key, document=document)
        except (ValueError, TypeError):
            # Runtime incompatibility follows the existing scoped refusal path:
            # unavailable legacy/profile facts cannot stop unrelated work.
            raise failure("BINDING_MISMATCH") from None
        if binding.document() != document:
            raise failure("BINDING_MISMATCH")
        return binding

    def _check_context(
        self,
        context: MaterializerContext,
        key: ReportingVerificationKey,
        policy: dict[str, Any],
        producer_key: str | None,
        source_binding: dict[str, Any] | None,
        destination_binding: dict[str, Any] | None,
    ) -> None:
        if producer_key is None:
            raise failure("BINDING_MISMATCH")
        offering = self._configuration_offering(
            context.configuration, context.binding, producer_key=producer_key
        )
        self._check_source_binding(context.configuration, producer_key, source_binding)
        if self._destination_binding(context.binding, offering).wire() != destination_binding:
            raise failure("BINDING_MISMATCH")
        if (
            policy != self._admission_policy()
            or offering.verification_key != key
            or verification_key_id(key) not in policy["verification_keys"]
            or context.obligation.generation_key != context.configuration.generation_key
        ):
            raise failure("BINDING_MISMATCH")

    def invalidate_schema_validation(self) -> None:
        """Drain first; an older scan cannot publish a new epoch's proof."""
        self._schema_epoch += 1
        self._schema_positive = None
        self._schema_task = None

    async def _schema_ready(self) -> bool:
        store = self.store
        if not store.durable:
            return False
        storage, epoch = store.storage_identity, self._schema_epoch
        identity = (id(storage), epoch)
        if self._schema_positive == identity:
            return True
        task = self._schema_task
        if task is None:

            async def scan() -> bool:
                try:
                    await store.validate_production_schema(
                        notifications=self.notifications_enabled,
                        service_context=self.source_registry is not None,
                    )
                    if epoch == self._schema_epoch and storage is store.storage_identity:
                        self._schema_positive = identity
                        return True
                    return False
                finally:
                    if self._schema_task is asyncio.current_task():
                        self._schema_task = None

            task = asyncio.create_task(scan())
            self._schema_task = task
            task.add_done_callback(lambda done: None if done.cancelled() else done.exception())
        if task.get_loop() is not asyncio.get_running_loop():
            return False
        return await asyncio.shield(task)

    async def start(self) -> None:
        if self._task is not None:
            self._assert_components()
            return
        self._assert_components(running=False)
        if self.store.durable and not await self._schema_ready():
            raise ReportingNotificationError("reporting_production_schema_unready")
        self._assert_components(running=False)
        self._task = asyncio.create_task(self._run(), name="adcp-reporting-production")
        if self.notification_workers:
            self._notification_task = asyncio.create_task(
                self._run_notifications(), name="adcp-reporting-production-notifications"
            )
        await self._started.wait()
        if self.notification_workers:
            await self._notification_started.wait()
        self._assert_components()

    async def _run(self) -> None:
        boundary: _WorkerBoundary = "producer"
        try:
            while not self._stop.is_set():
                # Each producer leases a generation through the reviewed fair
                # indexed acquisition path; no account enumeration is required.
                with source_turn():
                    for producer in dict.fromkeys(o.producer for o in self.offerings):
                        boundary = "producer"
                        token = self._producer_turn.set(producer)
                        try:
                            await producer.run_worker()
                        finally:
                            self._producer_turn.reset(token)
                boundary = "materializer"
                await self.materializer.run_once()
                boundary = "projection"
                await self.projection.rebuild_one()
                boundary = "sweeper"
                await self.projection.sweep_one()
                await self._maintain()
                self._started.set()
                try:
                    await asyncio.wait_for(self._stop.wait(), self.poll_seconds)
                except asyncio.TimeoutError:
                    pass
        except asyncio.CancelledError:
            self._stop.set()
            raise
        except Exception as error:
            already_stopping = self._stop.is_set()
            self._failed = True
            self._stop.set()
            if not already_stopping and not isinstance(error, ReportingNotificationError):
                _worker_stopped(boundary=boundary)
        finally:
            self._started.set()

    async def _maintain(self) -> None:
        """Scheduled retention: abandoned uploads, expired periods, old change rows.

        Each operation is bounded and resumable, runs only for the features the store
        opted into (row storage, the change feed), and a failure never stops the worker:
        the next interval retries and only the operation's name is logged.
        """
        if self.maintenance_seconds is None:
            return
        loop = asyncio.get_running_loop()
        if loop.time() < self._next_maintenance:
            return
        self._next_maintenance = loop.time() + self.maintenance_seconds
        from adcp.reporting.production._diagnostics import (
            _maintenance_failed,
            _maintenance_pending,
            _maintenance_stalled,
        )

        for name, run in self.store.maintenance_operations():
            try:
                result = await run()
            except asyncio.CancelledError:
                raise
            except Exception:
                _maintenance_failed(operation=name)
                self.maintenance_report[name] = {"failed": 1}
                continue
            counts = _counts(result)
            self.maintenance_report[name] = counts
            # Sweeps, pruning and retirement report per-item failures in their result instead of
            # raising; a binding that fails every pass must not be silent.
            if counts.get("failed"):
                _maintenance_failed(operation=name)
            # Records left in place on purpose are reported too, so "retirement does nothing"
            # is visible instead of looking like a healthy idle worker.
            pending = {
                key: counts[key]
                for key in ("protected", "held", "deferred", "skipped_unconfigured", "unsupported")
                if counts.get(key)
            }
            if pending:
                _maintenance_pending(operation=name, counts=pending)
            # Work nobody is reaching: intents expired past the overdue threshold, periods that
            # keep failing (five or more attempts), or orphan collection refused by another
            # database's claim on its namespace. The same signals the JavaScript SDK reports.
            stalled = {
                key: counts[key] for key in ("overdue", "stuck", "fenced") if counts.get(key)
            }
            if stalled:
                _maintenance_stalled(operation=name, counts=stalled)

    async def _run_notifications(self) -> None:
        from adcp.reporting.production.notifications import notification_turn

        try:
            while not self._stop.is_set():
                await notification_turn(self)
                self._notification_started.set()
                try:
                    await asyncio.wait_for(self._stop.wait(), self.poll_seconds)
                except asyncio.TimeoutError:
                    pass
        except asyncio.CancelledError:
            self._stop.set()
            raise
        except Exception as error:
            already_stopping = self._stop.is_set()
            self._failed = True
            self._stop.set()
            if not already_stopping and not isinstance(error, ReportingNotificationError):
                _worker_stopped(boundary="notifications")
        finally:
            self._notification_started.set()

    async def _check_notifications(self, account_id: str) -> None:
        from adcp.reporting.production.notifications import check_account_notifications

        self._assert_components()
        try:
            await check_account_notifications(self, account_id)
        except Exception:
            raise ReportingNotificationError("notification_chain_unready") from None
        self._assert_components()

    async def activate(self, *, account_id: str) -> bool:
        await self._check_notifications(account_id)
        await self.projection.activate(account_id=account_id)
        return await self.store.activate_production(account_id=account_id)

    async def aclose(self) -> None:
        self._stop.set()
        task = self._task
        if task is not None:
            # Drain short database turns instead of interrupting psycopg's
            # transaction entry/exit. Long I/O already has SDK-owned deadlines.
            await asyncio.gather(task, return_exceptions=True)
        if self._notification_task is not None:
            await asyncio.gather(self._notification_task, return_exceptions=True)
        self._notification_task = None
        self._task = None
        self._closed = True
        proof = self._schema_task
        if proof is not None:
            await asyncio.gather(proof, return_exceptions=True)
        if self.store.production_support is not None and self.store.production_support() is self:
            self.store.production_support = None

    async def reporting_delivery(self, *, extra: Mapping[str, Any] | None = None) -> dict[str, Any]:
        # Validate protected extra even when the concrete surface is unready.
        producer = self.offerings[0].producer
        payload = producer.advertised_reporting_delivery(
            consumer_status_task=self.projection.consumer_status_enabled,
            offerings=[],
            automated_recovery_window=self.automated_recovery_window,
            status_retention_days=self.status_retention_days,
            extra=extra,
        )
        try:
            if self._stop.is_set():
                return {}
            self._assert_components()
            if not await self._schema_ready():
                return {}
            # Catalog proof is cached; live component/mount ownership is not.
            # It must still hold after an awaited first scan or invalidation.
            self._assert_components()
            offerings = [o for o in self.offerings if self._offering_ready(o)]
            if not offerings:
                return {}
            writer = self.materializer.writer
            assert isinstance(writer, ReportingProductionDestination)
            payload.update(
                offerings=[o.wire() for o in offerings],
                managed_delivery=True,
                resource_retention_days=writer.resource_retention_days,
                authorization_revocation_seconds=writer.authorization_revocation_seconds,
            )
            if any(o.reconciled for o in offerings):
                payload.update(reconciled_billing=True, receipt_task="sync_reporting_receipts")
            if self.notification_workers:
                payload.update(
                    ledger_notification="reporting.ledger_changed",
                    readiness_notification="reporting.delivery_ready",
                    status_notification="reporting.status_changed",
                )
            return payload
        except Exception:
            return {}

Compose, mount, start, then activate accounts after draining old workers.

The owned worker performs indexed producer/materializer/projector turns. Stopping it prevents fresh admission while registered discovery remains stable. An optional HTTP notification worker is independent of polling readiness; enabled logical enqueue is always part of the materializer transaction.

Migrate with store.create_schema() before construction/start. For DDL, drain and close this support, migrate, and construct fresh support. Schema proofs do not detect arbitrary serving-time DDL or search-path changes.

Instance variables

prop keys : tuple[ReportingVerificationKey, ...]
Expand source code
@property
def keys(self) -> tuple[ReportingVerificationKey, ...]:
    return tuple(dict.fromkeys(o.verification_key for o in self.offerings))
var maintenance_report

The last pass's integer counters per operation, for health checks and dashboards.

prop notifications_enabled : bool
Expand source code
@property
def notifications_enabled(self) -> bool:
    return bool(self.projection.policy["notifications_enabled"])

Methods

async def aclose(self) ‑> None
Expand source code
async def aclose(self) -> None:
    self._stop.set()
    task = self._task
    if task is not None:
        # Drain short database turns instead of interrupting psycopg's
        # transaction entry/exit. Long I/O already has SDK-owned deadlines.
        await asyncio.gather(task, return_exceptions=True)
    if self._notification_task is not None:
        await asyncio.gather(self._notification_task, return_exceptions=True)
    self._notification_task = None
    self._task = None
    self._closed = True
    proof = self._schema_task
    if proof is not None:
        await asyncio.gather(proof, return_exceptions=True)
    if self.store.production_support is not None and self.store.production_support() is self:
        self.store.production_support = None
async def activate(self, *, account_id: str) ‑> bool
Expand source code
async def activate(self, *, account_id: str) -> bool:
    await self._check_notifications(account_id)
    await self.projection.activate(account_id=account_id)
    return await self.store.activate_production(account_id=account_id)
def invalidate_schema_validation(self) ‑> None
Expand source code
def invalidate_schema_validation(self) -> None:
    """Drain first; an older scan cannot publish a new epoch's proof."""
    self._schema_epoch += 1
    self._schema_positive = None
    self._schema_task = None

Drain first; an older scan cannot publish a new epoch's proof.

async def reporting_delivery(self, *, extra: Mapping[str, Any] | None = None) ‑> dict[str, typing.Any]
Expand source code
async def reporting_delivery(self, *, extra: Mapping[str, Any] | None = None) -> dict[str, Any]:
    # Validate protected extra even when the concrete surface is unready.
    producer = self.offerings[0].producer
    payload = producer.advertised_reporting_delivery(
        consumer_status_task=self.projection.consumer_status_enabled,
        offerings=[],
        automated_recovery_window=self.automated_recovery_window,
        status_retention_days=self.status_retention_days,
        extra=extra,
    )
    try:
        if self._stop.is_set():
            return {}
        self._assert_components()
        if not await self._schema_ready():
            return {}
        # Catalog proof is cached; live component/mount ownership is not.
        # It must still hold after an awaited first scan or invalidation.
        self._assert_components()
        offerings = [o for o in self.offerings if self._offering_ready(o)]
        if not offerings:
            return {}
        writer = self.materializer.writer
        assert isinstance(writer, ReportingProductionDestination)
        payload.update(
            offerings=[o.wire() for o in offerings],
            managed_delivery=True,
            resource_retention_days=writer.resource_retention_days,
            authorization_revocation_seconds=writer.authorization_revocation_seconds,
        )
        if any(o.reconciled for o in offerings):
            payload.update(reconciled_billing=True, receipt_task="sync_reporting_receipts")
        if self.notification_workers:
            payload.update(
                ledger_notification="reporting.ledger_changed",
                readiness_notification="reporting.delivery_ready",
                status_notification="reporting.status_changed",
            )
        return payload
    except Exception:
        return {}
async def start(self) ‑> None
Expand source code
async def start(self) -> None:
    if self._task is not None:
        self._assert_components()
        return
    self._assert_components(running=False)
    if self.store.durable and not await self._schema_ready():
        raise ReportingNotificationError("reporting_production_schema_unready")
    self._assert_components(running=False)
    self._task = asyncio.create_task(self._run(), name="adcp-reporting-production")
    if self.notification_workers:
        self._notification_task = asyncio.create_task(
            self._run_notifications(), name="adcp-reporting-production-notifications"
        )
    await self._started.wait()
    if self.notification_workers:
        await self._notification_started.wait()
    self._assert_components()
def validate_configuration(self,
value: ReportingConfigurationAdmission) ‑> None
Expand source code
def validate_configuration(self, value: ReportingConfigurationAdmission) -> None:
    value.check(self)