Actions & roles

The Vibe Commerce Protocol (VCP) is one protocol with four action namespaces. An action is a flat string of the form <namespace>.<verb>; the router splits on the first . to recover the namespace. What an action means lives in its namespace — who is allowed to send it lives in the permission matrix.

Throughout, money is integer minor units only — $3.00 is 300, never a float.

delegate.*

Human → agent. A human principal delegates authority to its agent; persona engines (or scenarios in their stead) emit these into the agent side.

• delegate.create_purchase_mandate — consumer hands the buyer a PurchaseMandate (the vibe intent, budget, constraints, and authority).
• delegate.approve_purchase — consumer approves a match certificate by cert_id; the human-in-the-loop authority gate before money moves.
• delegate.reject_purchase — consumer rejects a certificate with a reason.
• delegate.set_business_goal — merchant owner hands the merchant pricing role a sell mandate / OfferMandate.

commerce.*

Agent ↔ agent. The actual commerce interaction between buyer and merchant agents — discovery, negotiation, fulfillment, and support.

• commerce.search — buyer discovery asks the aggregator for matching offers.
• commerce.request_offer — buyer asks a merchant for an offer on a sku_id.
• commerce.propose_offer — carries a committed GroundedOffer (price, claims, fulfillment terms).
• commerce.counter_offer — either side counters with a revised GroundedOffer.
• commerce.accept_offer — either side accepts by offer_id.
• commerce.create_cart — buyer authorization builds an AP2-aligned cart.
• commerce.dispatch— merchant fulfillment's shipment intent.
• commerce.request_return — buyer requests a return on a tx_id.
• commerce.respond_inquiry — merchant support answers a pre-purchase question.

platform.*

Platform-only execution. Buyer and merchant agents may request these where permitted, but only platform roles execute them — this is marketplace governance.

• platform.rank_offers — aggregator returns a ranked candidate list to the buyer.
• platform.verify_claims — checks a GroundedOfferagainst the merchant's OfferMandate.permitted_claims.
• platform.create_match_certificate — issues a MatchCertificate attesting a mandate matched an offer truthfully under policy P at time T.
• platform.authorize_payment — PSP authorizes against a certificate plus payment instrument.
• platform.settle_payment — PSP settles the ledger transaction; the only path money moves on.
• platform.open_dispute — either side opens a dispute to the adjudicator.
• platform.rule_dispute — adjudicator issues a ruling to both sides.
• platform.update_reputation — reputation role writes a reputation delta.

world.*

Ground-truth state. Reads are scoped per role; writes are restricted. The runtime materializes every write as a TransactionStateDiff.

• world.read_catalog — public, any agent.
• world.read_inventory — scoped: merchant:* and platform:* (buyers read inventory only via search results).
• world.read_order, world.read_ledger, world.read_dispute — scoped to the parties of that record plus platform:*.
• world.create_order, world.reserve_inventory, world.update_ledger — restricted to platform:psp.
• world.update_catalog / world.update_inventory— restricted to the merchant's catalog / fulfillment roles, never the buyer.
• world.update_reputation — restricted to platform:reputation.

The permission matrix

The real protocol boundary is not the namespace — it is the role → allowed-actions table. VCP materializes this as PARTITION_ALLOW in src/protocol/actions.py: a map from each action to its permitted sender and receiver side prefixes. The router enforces it at register time and again on every send, matching the side prefix of an agent's id (so buyer and buyer:intent both resolve to the buyer side).

A summary of who may do what. Only platform:psp moves money; only the platform issues match certificates and writes reputation; only platform:adjudicator rules disputes; buyers never write the world.

Money moves only through platform:pspand inventory writes only through the merchant's fulfillment role — the matrix gates each independently, even though both show under the platform and merchant columns respectively.

Non-negotiable invariants

The invariants the matrix exists to encode:

• No agent ever writes its own reputation — reputation is a platform monopoly via platform:reputation.
• No buyer writes the world directly — money and inventory move only through platform:pspand the merchant's fulfillment role.
• No merchant rules its own dispute — adjudication is a platform monopoly via platform:adjudicator.
• The audit log is runtime-only — agents cannot forge entries or skip them.
• Private-utility content never rides in a payload — independent of the matrix, the router rejects any envelope whose payload leaks values from the sender's private-utility store (a max budget, a floor price). The matrix gates who can send what; this check gates what can ride inside.