How sutra actually works.

A mandate — the one term on this page worth defining up front — is a permission, not a payment: “let this one merchant charge this one card up to this one amount, one time.” Creating a mandate moves no money. The engine asks Prava to create a mandate session (POST /v1/sessions) and hands the member a link to Prava’s own hosted page. What happens next is the one step in this entire system that no script, agent, or plugin can perform: the member opens that page on their own device and approves with their own passkey. The engine is not in that loop at all — it finds out later, by asking.

Only when the group’s rule is satisfied does the engine call POST /v1/mandates/:id/charge. That call is where Prava mints a single-use, merchant-locked card credential for a supported adapter. Everything upstream of it — discovery, planning, cart-building, reading a page you’re on — is free of money by construction, not by policy: none of those code paths hold a Prava key capable of a charge.

mcp/src/server.ts · extension/content.js · widget/bookmarklet.js · nanda-town-prava/nanda_town_prava/plugin.py

collecting is where every group starts and where it spends almost all its life: members open their link, approve or decline, or simply run out the clock. The type also declares an eighth status, draft — it is never assigned anywhere in the code (one grep hit: the declaration itself), so it is left off this diagram on purpose. The spec’s deciding state is real in the same way: decide() evaluates the group’s rule and, if it passes, locks the approver set and moves straight to committing in the same synchronous call — no group row is ever observed sitting in deciding.

committing is deliberately a one-way door: cancelGroup() throws “cannot cancel past the point of no return” the instant a group reaches it, because the first charge call is about to fire and a card charge does not have an undo button.

On the member side, the dashed amber line is a detail worth having exactly right, because it is easy to get backwards: when a price drift pushes someone over their approved cap, requoteCascade() resets them not to “awaiting approval” but all the way back to viewed — because it is openMember(), entered from viewed, that mints the fresh mandate session at the new share. Consent cannot silently stretch to cover a higher number; a requote is capped at two rounds, then the group aborts rather than asking a third time.

If the group’s locked members can’t quite cover the total at their approved caps — a straggler dropped out, or price drifted — the shortfall goes to any armed backstop first: someone who pre-authorised a second, separate mandate as a standing offer to cover exactly this. Only if no backstop covers it does the group requote. This is the closest thing in the system to group credit, and it still never pools a cent — a backstop’s money moves from their own card, through their own mandate, the same way everyone else’s does.

The charge call itself has three outcomes, and conflating any two of them is exactly how a system double-charges someone or gets stuck forever:

• A 4xx response is a definite no. Prava has already told us nothing was charged; retrying it burns time and risks a second definite no reading like doubt.
• A transport failure is genuinely unknown — the request may have landed. Before doing anything else, the engine asks Prava’s own record of that mandate’s charges for the reference it sent. Found it → adopt that transaction id, never reissue. Still not there after retries → the state is recorded as unknown, which is a first-class outcome, not a bug: the group stays in committing and a background poller resumes it later under the exact same idempotency reference.
• A success is written to the database as charged before the (slower, separately retried) settlement report is even attempted — because a restart between those two steps used to leave the database saying “charging” for a card that had already been billed, and the resumed saga would mint a fresh reference and charge it again.

At the end, every mandate that was never charged is explicitly cancelled, and the receipt is Ed25519-signed and hash-chained (engine/src/receipt.ts) so anyone — a member, a judge — can verify it offline against the printed public key, without trusting sutra’s UI at all.

A URL proves product provenance, never payment capability. Discover requires a person to choose Shopify POS or checkout handoff. The extension is always checkout handoff. Venue plans stay plans until a real bill exists; a chosen OpenStreetMap point is never treated as a checkout.

On the honest rail, a member’s consent is a real act with its own HTTP route — not a gap: POST /v1/members/:id/accept calls acceptShare(), which is deliberately a different act from a passkey mandate so the receipt can never blur the two. Reaching committed here means every amount is agreed and recorded; it never means a card was touched.

The bottom of the diagram is the part worth trusting most: verifyReceipt() is a pure function anyone can run offline against a receipt file. It rejects a non-zero charged amount on every non-charging capability, including Shopify POS and checkout handoff.

A model may propose the slots (category, timing, place, budget) from free text, but a deterministic pass is the floor and always runs underneath it — with no key and no network, the same sentence still parses. The model never picks a venue, never sets a price, and never invents a coordinate: it reports a place phrase, and a real geocoder (OpenStreetMap Nominatim) turns that into an actual location.

Ranking is a pure function over real data — five weighted factors (how well the time works, how far people travel, whether it fits the budget, group preference, and freshness), and every one of them renders as a sentence a person can check by hand against the numbers, not a black box score.

convertToGroup() is the only door between the two layers, and it only opens one way: once a group hands its chosen option through it, the plan is marked converted and the coordination layer never touches that group again. This boundary is why an agent that speaks only /v1/groups is a complete GMP/1 client — this entire layer, real venues and all, is optional product built on top, not the protocol.