Struct ProtocolCorrelator 

pub struct ProtocolCorrelator { /* private fields */ }

Available on crate feature payments only.

Cross-protocol correlator that routes ACP and AP2 adapters through the same canonical transaction ID and journal model.

The correlator enforces three rules:

1. Both protocols share one canonical TransactionId per transaction.
2. Protocol-specific identifiers are correlated in ProtocolRefs without assuming they are interchangeable.
3. Direct protocol-to-protocol conversion is refused when it would lose semantics or accountability evidence.

Implementations

impl ProtocolCorrelator

pub fn new(transaction_store: Arc<dyn TransactionStore>) -> ProtocolCorrelator

Creates a new correlator backed by the canonical transaction store.

pub async fn get_transaction( &self, lookup: TransactionLookup, ) -> Result<Option<TransactionRecord>, AdkError>

Looks up a canonical transaction by its internal ID.

pub async fn find_by_acp_checkout_session_id( &self, session_identity: Option<AdkIdentity>, acp_checkout_session_id: &str, ) -> Result<Option<TransactionRecord>, AdkError>

Looks up a canonical transaction by an ACP checkout session ID.

Scans unresolved transactions for a matching protocol_refs.acp_checkout_session_id. For production use, a dedicated index would be more efficient.

pub async fn find_by_ap2_mandate_id( &self, session_identity: Option<AdkIdentity>, mandate_id: &str, ) -> Result<Option<TransactionRecord>, AdkError>

Looks up a canonical transaction by an AP2 mandate ID (intent, cart, or payment).

pub fn attach_protocol_ref( record: &mut TransactionRecord, kind: ProtocolRefKind, value: String, ) -> Result<(), PaymentsKernelError>

Attaches a protocol-specific reference to an existing transaction record.

This is the canonical way to correlate ACP and AP2 identifiers under one transaction. The correlator never overwrites an existing reference slot with a different value.

Errors

Returns an error if the slot is already occupied by a different value.

pub fn correlated_refs(record: &TransactionRecord) -> &ProtocolRefs

Returns all protocol identifiers correlated to one canonical transaction.

pub fn contributing_protocols(record: &TransactionRecord) -> Vec<String>

Returns the set of protocol names that have contributed evidence to this transaction.

pub fn is_dual_protocol(record: &TransactionRecord) -> bool

Returns true when both ACP and AP2 have contributed to this transaction.

impl ProtocolCorrelator

Best-effort canonical projections where ACP or AP2 data can be mapped safely without semantic loss.

These projections are intentionally one-directional: protocol data is projected into canonical kernel types. The kernel never projects canonical data back into a different protocol’s wire format because that would fabricate provenance.

pub fn project_acp_cart_to_canonical( record: &TransactionRecord, ) -> ProjectionResult<Cart>

Projects an ACP cart (line items + totals) into the canonical cart model.

This projection is safe because ACP line items, totals, and currency map directly to canonical Cart fields without losing structure.

pub fn project_ap2_cart_to_canonical( record: &TransactionRecord, ) -> ProjectionResult<Cart>

Projects an AP2 cart mandate’s payment details into the canonical cart model.

This projection is safe because AP2 PaymentRequest.details.displayItems and total map to canonical CartLine and Cart.total without losing the item-level structure.

pub fn project_order_to_canonical( record: &TransactionRecord, ) -> ProjectionResult<OrderSnapshot>

Projects ACP or AP2 order updates into the canonical order snapshot.

Both protocols produce order state that maps to the canonical OrderSnapshot without semantic loss.

pub fn project_settlement_state( record: &TransactionRecord, ) -> ProjectionResult<TransactionState>

Projects the canonical transaction state into a protocol-neutral settlement summary.

Both ACP order updates and AP2 payment receipts can update canonical settlement state, so this projection is safe in both directions.

pub fn project_fulfillment_to_canonical( record: &TransactionRecord, ) -> ProjectionResult<FulfillmentSelection>

Projects the canonical fulfillment selection.

Both ACP fulfillment options and AP2 shipping options map to the canonical FulfillmentSelection without semantic loss.

pub fn project_payment_method( record: &TransactionRecord, ) -> ProjectionResult<PaymentMethodSelection>

Projects the canonical payment method selection.

Both ACP payment handlers and AP2 payment response method names map to the canonical PaymentMethodSelection without semantic loss.

impl ProtocolCorrelator

Guards against unsafe direct protocol-to-protocol conversions.

The kernel mediates all cross-protocol operations. These guards return explicit errors when a direct ACP-to-AP2 or AP2-to-ACP conversion would lose semantics or accountability evidence.

pub fn refuse_acp_delegate_to_ap2_authorization( field: &str, ) -> Result<(), PaymentsKernelError>

Refuses direct conversion of an ACP delegated payment token to an AP2 user authorization credential.

ACP delegated payment tokens are scoped PSP credentials with merchant and amount constraints. AP2 user authorization artifacts are cryptographic proofs of user consent. Converting one to the other would fabricate provenance.

pub fn refuse_ap2_authorization_to_acp_delegate( field: &str, ) -> Result<(), PaymentsKernelError>

Refuses direct conversion of an AP2 signed user authorization to an ACP delegated payment token.

AP2 user authorization presentations prove user consent through cryptographic signatures. ACP delegated payment tokens are PSP-issued scoped credentials. Converting one to the other would lose the cryptographic accountability chain.

pub fn refuse_acp_session_to_ap2_mandate( field: &str, ) -> Result<(), PaymentsKernelError>

Refuses direct conversion of ACP checkout session state to AP2 mandate state.

ACP checkout sessions are merchant-facing HTTP resources with server-managed lifecycle. AP2 mandates are signed authorization artifacts with explicit role separation. The state models are not equivalent.

pub fn refuse_ap2_mandate_to_acp_session( field: &str, ) -> Result<(), PaymentsKernelError>

Refuses direct conversion of AP2 mandate state to ACP checkout session state.

AP2 mandates carry cryptographic authorization chains and role-separated provenance. ACP checkout sessions are server-managed merchant resources. Direct conversion would discard the mandate’s authorization evidence.

pub fn require_kernel_mediation( record: &TransactionRecord, source: ProtocolOrigin, target: ProtocolOrigin, operation: &str, ) -> Result<(), PaymentsKernelError>

Validates that a cross-protocol operation goes through the kernel rather than attempting direct protocol-to-protocol transcoding.

Returns Ok(()) when the operation is kernel-mediated (both sides use the canonical transaction). Returns an error when the caller attempts to bypass the kernel.