Cumulative state across mandate fulfilments -- where does it live?

[timaxorum]

Reading through the v0.2 spec and samples, I've been trying to map how state evolves across the mandate lifecycle when a single Intent Mandate authorizes multiple fulfillments over time. I think there's a design question worth surfacing — possibly already settled and I missed it, possibly genuinely open. Posting here rather than as an Issue because it feels more like "where does this concept live" than "something is broken."

The scenario I keep coming back to:

A user signs an Intent Mandate authorizing their agent to spend up to $200 on groceries over the next 7 days. The agent fulfills three carts during that window — $80 Monday, $60 Wednesday, $90 Friday. Each individual Cart Mandate, taken in isolation, is consistent with the Intent. Cumulatively, the third transaction breaches what the user authorized.

Each fulfillment produces its own Cart and Payment Mandate, properly signed and chain-valid. The verifier checking the third payment sees a well-formed mandate chain. The breach is only visible if the verifier knows about the prior two fulfillments — which means somebody is maintaining cumulative state against the Intent Mandate ID across the lifecycle.

The spec is (correctly, I think) silent on where this happens. But the silence creates a question:

1. Is cumulative-constraint enforcement considered in scope for AP2 itself, or is it explicitly downstream of the protocol — something every implementer is expected to build into their merchant-side, agent-side, or network-side infrastructure independently?

2. If it's downstream, is there a canonical place for it to live? Candidates I can think of:

   • Credential Provider — knows about issuance, would need a way to be informed of fulfillments
   • Merchant of Record — knows about its own transactions but not those at other merchants
   • Agent platform — knows the full agent activity but is also the party being constrained
   • Network / scheme — has visibility across merchants but adds a centralization point
   • A separate ledger/accounting layer downstream of all of these — which is what I keep gravitating toward

3. If multiple parties end up tracking partial views, what's the reconciliation story? Is there an expectation that the Intent Mandate ID becomes a join key across systems that currently don't share state?

The reason I'm chewing on this: the same Intent Mandate ID that proves authorization upstream becomes the natural causation key for whatever system records what actually happened downstream. Whether that downstream system is part of AP2's scope or pointedly outside it shapes a lot of design choices for anyone building near this protocol.

Curious whether this has come up in design discussions, whether there's a documented stance, or whether it's deliberately left to implementers. Either answer is useful — I just want to understand the intended boundary before assuming.

— Tim

[chopmob-cloud]

@timaxorum — this is genuinely open in the spec text, but it's been operationally answered a few different ways in production. Sharing what AlgoVoi landed on after hitting the same problem with our APM (Agentic Payment Mandates) work, plus how it compares to the other patterns surfacing in the AP2 thread.

The short answer

Cumulative state lives wherever a single party sits on the path of every settlement. Of your 5 candidate layers, only one of them actually has that property in a given deployment, and the answer changes by deployment topology — which is why the spec is correctly silent on this.

For AlgoVoi specifically: we sit on the path because we pay the merchant on-chain from our hot wallet and bill the human via a prepaid GBP balance. The cumulative counter lives in a single Postgres row keyed on (account_id, period_key), and mandate_id is the join key on the way in. Other deployments will hit the same question with different topology and land somewhere else; the pattern that works depends on who has the universal view.

Operational walkthrough — AlgoVoi APM

We hit your exact $200/week scenario (with £ rather than $ because UK regulator). What we landed on after working through the same 5 candidates you list:

Three orthogonal cumulative caps, enforced atomically on every balance-increase path:

Cap	Limit	What it binds
Per-mandate	£100 hard cap	The JWT — if the agent loses control, this is the blast radius
Per-account	£300 aggregate	The human — total exposure across all their mandates
Max active mandates	3 per account	Bounds the proliferation surface

Worst-case human exposure: £300. Worst-case per-mandate exposure: £100. Cumulative across 7-day window: tracked in period_spent_minor on the mandate row.

TOCTOU protection is the critical bit your 5-candidates question implicitly raises. Every payment-decision path holds an advisory lock on hashtext(mandate_id) BEFORE reading the cumulative counter, decrements it inside the same transaction, then commits. Without that, two concurrent fulfilments can both pass the cumulative check and breach the cap. We use pg_advisory_xact_lock(hashtext(jti)) where jti is the mandate token UUID.

POST /mandate/pay
  ├─ decode mandate JWT → jti
  ├─ pg_advisory_xact_lock(hashtext(jti))    ← TOCTOU guard
  ├─ SELECT mandate WHERE token_jti=jti FOR UPDATE
  ├─ Validate: status=active, not expired, balance>0, merchant in whitelist
  ├─ Check amount ≤ per-mandate cap (binds the JWT)
  ├─ Check (period_spent + amount) ≤ period_cap (cumulative — the answer to your question)
  ├─ Check amount ≤ balance (human pre-funded)
  ├─ call_facilitator_payout(...)
  ├─ UPDATE balance + period_spent (atomic with the read)
  ├─ INSERT mandate_charges ledger row
  └─ COMMIT

Lazy period reset: when the period boundary is crossed (weekly window in your example), the next pay call resets period_spent_minor = 0. Eager reset would create a thundering-herd reset job; lazy reset means the boundary cost is paid by whichever charge happens to cross it, amortised.

Comparing to your 5 candidate layers

Your candidates fail (in our deployment) for specific reasons worth surfacing:

Candidate	Why it doesn't work	Why it might work in YOUR deployment
Credential Provider	Issues mandates, never sees fulfilments	Works if CP is also on the settlement path (some integrated stacks)
Merchant of Record	Blind to spend at other merchants	Works ONLY for single-merchant intent mandates
Agent platform	Is the constrained party — clear conflict of interest	Works if the agent platform is the user's trusted custodian (e.g. an embedded agent inside a hosted wallet they directly chose)
Network / scheme	Centralisation + only sees on-chain rail (blind to fiat / off-chain corrections)	Works for pure on-chain settlement-only deployments (RIVR pattern — see #255)
Separate downstream ledger	Depends on every other party reporting honestly to it	Works if the ledger has signed-receipt enforcement on every report

The 6th candidate (which we landed on): whichever single party is on the path of every settlement. For AlgoVoi that's the gateway. For @hilarl's RIVR proposal in #255, it's the on-chain token contract. For a Stripe-equivalent deployment, it would be the merchant-side payment processor.

The pattern that emerges is: cumulative state is a property of the topology, not a property of AP2. AP2 correctly stays silent on where, because the right answer depends on the deployment shape. What AP2 COULD codify (non-normatively) is the rule "cumulative-state custodian MUST be on the settlement path; if no single party is, the deployment cannot enforce cumulative constraints".

Cross-pattern comparison

The interesting design split surfacing in the AP2 thread is:

Pattern	Cumulative counter lives in	Authority of truth	Cross-rail support
AlgoVoi APM	Platform-side Postgres row	Platform balance ledger	✅ Multi-chain (we span 8)
RIVR (#255)	ERC-20 token contract storage	On-chain refusal at token-transfer time	❌ Single-chain per deployment
Centralised network (theoretical)	Network scheme database	Network-mediated	Multi-rail if the network covers them
Pure off-chain ledger (theoretical)	Standalone ledger service	Depends on signed-receipt reporting	Multi-rail at the cost of reporting integrity

@Ectsang touched on this in #207 (cross-merchant budget enforcement for IntentMandates) — same problem at a different cell of the matrix. The 7-day-window example in your post and the cross-merchant example in #207 are the same underlying cumulative-state question framed at different cardinalities (time vs space).

Join-key question (your #3)

Yes, mandate_id (or intent_mandate_id) becomes the join key across systems that currently don't share state. We hit this in production: our mandate_charges ledger has (mandate_id, tenant_id, resource_id, amount_minor, chain, tx_id, charged_at) — five different downstream systems (chain settlement scanner, merchant webhook, audit-bundle anchor, refund handler, reconciliation job) all key off mandate_id.

For cross-platform reconciliation (e.g. RIVR's on-chain counter + AlgoVoi's platform ledger both seeing the same mandate), the join key should be (intent_mandate_id, billing_period_index) where billing_period_index is derived deterministically from mandate.issued_at + period. That's the same dedup pattern locking in across the x402-foundation/x402#2334 JCS_hash rule — (JCS_hash, anchor_chain, block_number) uniqueness within declared observation window. Conceptually identical: deterministic key from the authoritative artefact + time-bounding component.

Where this could land in AP2 spec text

Probably not as normative requirement (since the deployment topology determines where the counter goes), but possibly as informative pattern documentation: enumerate the 4 cumulative-state patterns (platform-side ledger / on-chain authority / network-mediated / separate downstream), the topology each requires, and the join-key convention. Implementers reading the spec would then have a checklist: "which of these 4 patterns does my deployment fit, and what's my join-key story?"

Happy to draft this as a follow-on note to AP2 sample docs if there's appetite, since the same content directly extends the regulatory worked example from x402-foundation/x402#2322 §3 and aligns with the cross-rail composition discussion at #255.

---

cc @hilarl for the RIVR cross-pattern reference; cc @Ectsang re #207 cross-merchant variant.

Useful discussion — the silence-in-spec is right but the silence-in-docs is the gap worth filling.

---

AlgoVoi (chopmob-cloud) -- Acquisition enquiries: https://docs.algovoi.co.uk/acquisition