Module adcp.reporting.ledger.status_snapshot
Optional status participants and connection-bound snapshot/lifecycle helpers.
Functions
def apply_memory_intents(store: InMemoryReportingLedgerStore,
intents: tuple[StatusLifecycleIntent, ...]) ‑> None-
Expand source code
def apply_memory_intents( store: InMemoryReportingLedgerStore, intents: tuple[StatusLifecycleIntent, ...] ) -> None: for intent in intents: issue = intent.lifecycle key = (issue.account_id, issue.issue_key) store._issues[key] = issue store._issue_generations[key] = max(store._issue_generations.get(key, 0), issue.generation) store._dirty_issue(issue, intent.scope, enqueue=False) def memory_snapshot(store: InMemoryReportingLedgerStore, account_id: str) ‑> ReportingStatusSnapshot-
Expand source code
def memory_snapshot( store: InMemoryReportingLedgerStore, account_id: str ) -> ReportingStatusSnapshot: """Caller holds the memory transaction. No public method or lock acquisition.""" statuses = tuple(s for s in store._statuses.values() if s.account_id == account_id) issues = tuple(i for i in store._issues.values() if i.account_id == account_id) consumer_ids = {s.consumer_id for s in statuses} | { i.consumer_id for i in issues if i.consumer_id is not None } # Reconciliation subclasses retain independently scoped destination/receipt evidence. for _, who, _ in getattr(store, "_delivery_records", []): if who.account_id == account_id: consumer_ids.add(who.consumer_id) return ReportingStatusSnapshot( account_id=account_id, as_of=store._clock(), configurations=tuple( c for c in store._configurations.values() if c.account_id == account_id ), obligations=tuple(o for o in store._obligations.values() if o.account_id == account_id), revisions=tuple(r for r in store._revisions.values() if r.account_id == account_id), statuses=statuses, lifecycles=issues, issue_scopes=tuple( (i, s) for (a, i), s in store._issue_status_scopes.items() if a == account_id ), consumer_ids=tuple(sorted(consumer_ids)), adjustments=tuple(a for a in store._adjustments.values() if a.account_id == account_id), changes=tuple( (seq, kind, record_id, store._change_owners[seq]) for seq, a, kind, record_id, _ in store._changes if a == account_id ), )Caller holds the memory transaction. No public method or lock acquisition.
def settle_memory_snapshot(store: InMemoryReportingLedgerStore, account_id: str) ‑> ReportingStatusSnapshot-
Expand source code
def settle_memory_snapshot( store: InMemoryReportingLedgerStore, account_id: str ) -> ReportingStatusSnapshot: for _ in range(3): snapshot = memory_snapshot(store, account_id) intents = lifecycle_intents(snapshot) if not intents: return snapshot apply_memory_intents(store, intents) raise ReportingNotificationError("status_lifecycle_did_not_converge") def snapshot_from_storage(raw: dict[str, Any]) ‑> ReportingStatusSnapshot-
Expand source code
def snapshot_from_storage(raw: dict[str, Any]) -> ReportingStatusSnapshot: """Decode the exact SQL boundary input through the ledger's existing mappers.""" from adcp.reporting.ledger._record_rows import ( _ADJUSTMENT_COLUMNS, _ISSUE_COLUMNS, _OBLIGATION_COLUMNS, _REVISION_COLUMNS, _STATUS_COLUMNS_BARE, _adjustment_from_row, _configuration_from_row, _issue_from_row, _obligation_from_row, _revision_from_row, _status_from_row, ) from adcp.reporting.ledger.notification_models import decode_status_scope dates = { "activated_at", "deactivated_at", "period_start", "period_end", "expected_at", "scope_resolved_at", "automated_recovery_deadline_at", "created_at", "observed_at", "data_through", "finalized_at", "status_as_of", "recorded_at", "seller_ledger_as_of", "opened_at", "retired_at", "accounting_period_start", "accounting_period_end", "correction_observed_at", } def decode(key: str, columns: str, builder: Callable[[Any], Any]) -> tuple[Any, ...]: names = [name.strip() for name in columns.split(",")] result = [] for row in raw.get(key, []): values = [ (aware_timestamp(row[n]) if n in dates and row.get(n) is not None else row.get(n)) for n in names ] result.append(builder(values)) return tuple(result) configurations = decode( "configurations", ( "delivery_config_id, delivery_config_version, account_id, report_definition_id," " reporting_profile, feed_purpose, required_finality, account_timezone, schedule," " media_buy_ids, activated_at, deactivated_at, automated_recovery_seconds," " status_retention_days, definition, authoritative_party, consumer_id, quarantined" ), _configuration_from_row, ) statuses = decode("statuses", _STATUS_COLUMNS_BARE, _status_from_row) lifecycles = decode( "lifecycles", _ISSUE_COLUMNS + ", waived_reporting_status_id, waived_conflict_sha256", _issue_from_row, ) waivers = { (w["account_id"], w["issue_key"], w["generation"]): w for w in raw.get("waivers", []) } lifecycles = tuple( ( replace( issue, waived_reporting_status_id=binding["reporting_status_id"], waived_conflict_sha256=binding["conflict_sha256"], ) if (binding := waivers.get((issue.account_id, issue.issue_key, issue.generation))) else issue ) for issue in lifecycles ) consumers = {row["consumer_id"] for row in raw.get("consumers", [])} consumers.update(s.consumer_id for s in statuses) consumers.update(i.consumer_id for i in lifecycles if i.consumer_id is not None) return ReportingStatusSnapshot( account_id=raw["account_id"], as_of=aware_timestamp(raw["as_of"]), configurations=configurations, obligations=decode("obligations", _OBLIGATION_COLUMNS, _obligation_from_row), revisions=decode("revisions", _REVISION_COLUMNS, _revision_from_row), statuses=statuses, lifecycles=lifecycles, issue_scopes=tuple( (row["issue_id"], decode_status_scope(row["scope"])) for row in raw.get("issue_scopes", []) ), consumer_ids=tuple(sorted(consumers)), adjustments=decode("adjustments", _ADJUSTMENT_COLUMNS, _adjustment_from_row), changes=tuple( (row["seq"], row["record_kind"], row["record_id"], row["consumer_id"]) for row in raw.get("changes", []) ), )Decode the exact SQL boundary input through the ledger's existing mappers.
def validate_status_evidence(status: ConsumerStatusRecord, snapshot: ReportingStatusSnapshot) ‑> None-
Expand source code
def validate_status_evidence( status: ConsumerStatusRecord, snapshot: ReportingStatusSnapshot ) -> None: """Repeat ingest validation under the source transaction's account lock. Transport validation cannot fence a concurrent restatement. These readers consume only already captured evidence and never acquire a connection. """ from adcp.reporting.ledger.consumer_status import validate_consumer_status_timing from adcp.reporting.ledger.store import LedgerConflictError generation = next( (c for c in snapshot.configurations if c.generation_key == status.generation_key), None ) if generation is None: raise LedgerConflictError( "UNKNOWN_CONFIGURATION_GENERATION", "status generation is unavailable" ) if status.report_definition_id != generation.report_definition_id: raise LedgerConflictError("REPORT_DEFINITION_MISMATCH", "status definition differs") if (status.seller_ledger_snapshot_id is None) != (status.seller_ledger_as_of is None): raise LedgerConflictError( "SELLER_SNAPSHOT_EVIDENCE_INCOMPLETE", "seller snapshot evidence is incomplete" ) obligation = next( (o for o in snapshot.obligations if status_matches_obligation(status, o)), None, ) if status.reporting_obligation_id is not None: # Trusted legacy writers retained a claimed ID on obligation_missing # before an account-local obligation existed. It is never an ownership # coordinate: attachment uses the validated generation and period only. # Public ingest still resolves every supplied ID before this participant. if obligation is None and status.consumer_status != "obligation_missing": raise LedgerConflictError("LOOKUP_UNAVAILABLE", "status evidence is unavailable") if obligation is not None and ( obligation.generation_key != status.generation_key or obligation.report_definition_id != status.report_definition_id or obligation.period.start != status.period_start or obligation.period.end != status.period_end ): raise LedgerConflictError("OBLIGATION_IDENTITY_MISMATCH", "status evidence differs") validate_consumer_status_timing(status, generation, as_of=snapshot.as_of) required = None if obligation is not None: revisions = tuple( r for r in snapshot.revisions if r.reporting_obligation_id == obligation.reporting_obligation_id ) selection = select_reporting_revision( revisions, account_id=obligation.account_id, reporting_obligation_id=obligation.reporting_obligation_id, required_finality=obligation.required_finality, ) if selection.kind == "corrupt": raise LedgerConflictError("HISTORY_UNAVAILABLE", "the revision history requires repair") if selection.kind == "selected": required = selection.revision if status.reporting_revision_id is None: return revision = next( (r for r in snapshot.revisions if r.reporting_revision_id == status.reporting_revision_id), None, ) if revision is None or ( obligation is not None and revision.reporting_obligation_id != obligation.reporting_obligation_id ): raise LedgerConflictError("LOOKUP_UNAVAILABLE", "status evidence is unavailable") if status.consumer_status == "content_mismatch" and obligation is not None: if required is None or required.reporting_revision_id != status.reporting_revision_id: raise LedgerConflictError( "REVISION_NOT_CURRENTLY_REQUIRED", "status revision is no longer required" )Repeat ingest validation under the source transaction's account lock.
Transport validation cannot fence a concurrent restatement. These readers consume only already captured evidence and never acquire a connection.
Classes
class ReportingStatusParticipant (*args, **kwargs)-
Expand source code
@runtime_checkable class ReportingStatusParticipant(Protocol): """Optional upgrade; existing ReportingLedgerStore implementations stay valid.""" async def read_status_snapshot(self, *, caller: ReportingCaller) -> ReportingStatusSnapshot: ... async def record_consumer_status_with_lifecycle( self, status: ConsumerStatusRecord ) -> tuple[ConsumerStatusRecord, bool]: ...Optional upgrade; existing ReportingLedgerStore implementations stay valid.
Ancestors
- typing.Protocol
- typing.Generic
Methods
async def read_status_snapshot(self, *, caller: ReportingCaller) ‑> ReportingStatusSnapshot-
Expand source code
async def read_status_snapshot(self, *, caller: ReportingCaller) -> ReportingStatusSnapshot: ... async def record_consumer_status_with_lifecycle(self, status: ConsumerStatusRecord) ‑> tuple[ConsumerStatusRecord, bool]-
Expand source code
async def record_consumer_status_with_lifecycle( self, status: ConsumerStatusRecord ) -> tuple[ConsumerStatusRecord, bool]: ...