Developers/Object & field reference
REFERENCE

Object & field reference

A terse field dictionary for VCP — the Vibe Commerce Protocol. The universal envelope plus the five shared objects, every field with its type and one-line meaning. Money fields are integer minor units everywhere.

Envelope

One shape on the wire for every message; the inner schema is set by action.kind.

  • protocol — str — always "vcp"; lets a bus carry non-VCP traffic unambiguously.
  • version — str — semver MAJOR.MINOR; wire-additive, fields added never removed.
  • msg_id — str (uuid v4) — globally unique; audit-log primary key.
  • ts — ts (RFC 3339) — timestamp with timezone; used for ordering and freshness windows.
  • from — str — sender side/role id (buyer, merchant[:n], platform, consumer:persona, merchant:owner); the Router keys on the side prefix.
  • to — str — receiver id; world for world-table ops, * reserved.
  • session_id — str — one per buyer-side journey; negotiation rounds nest via in_reply_to.
  • in_reply_to — str | null — msg_id this responds to, or null for a session-opening message.
  • idempotency_key — str | null — REQUIRED on state-changing actions; idempotent on (from, key), ≤255 chars, ≥24h retention.
  • signature — str | null — reserved; null unless a signed-envelope scenario (AP2-style ECDSA).
  • action.kind — str — namespaced action name; split on first "." to recover (namespace, verb).
  • action.payload — object — JSON payload whose schema is determined by action.kind.

PurchaseMandate

What the user wants and authorizes; embeds the AP2 mandate triad plus the VCP authority block.

  • mandate_id — str (uuid) — stable across the journey.
  • ap2_intent_mandate.goal — str — natural-language vibe intent.
  • ap2_intent_mandate.merchants — list[str] | null — AP2 allowed_merchants.
  • ap2_intent_mandate.skus — list[str] | null — constrained SKUs, if any.
  • ap2_intent_mandate.requires_refundability — bool — refundability required.
  • ap2_intent_mandate.intent_expiry — ts — intent expiry timestamp.
  • authority.can_buy_without_confirmation — bool — may settle without human approval.
  • authority.max_spend_without_confirmation — int — autonomy ceiling, minor units.
  • authority.can_negotiate — bool — may run counter-offer rounds.
  • authority.can_accept_substitutes — bool — may accept a substitute SKU.
  • authority.can_share_with_merchant — list[str] — fields the agent may disclose.
  • authority.must_not_share_with_merchant — list[str] — disclosure denylist; tagged PRIVATE_UTILITY.
  • hard_constraints.budget — int — mandate-fail ceiling, minor units.
  • hard_constraints.delivery_days — int — max acceptable delivery days.
  • hard_constraints.must_have — list[str] — required attributes; mandate-fail if missing.
  • soft_preferences.style — list[str] — tradeable style preferences.
  • soft_preferences.avoid — list[str] — tradeable dislikes.
  • taste.aesthetic — str — persona-conditioned aesthetic.
  • taste.occasion — str — use occasion.
  • taste.social_signal — str — intended social signal.
  • ap2_cart_mandate — CartMandate | null — AP2 checkout mandate; null until a cart exists.

OfferMandate

The merchant-side dual; bounds where the pricing role may operate.

  • mandate_id — str — merchant mandate id.
  • merchant_id — str — owning merchant.
  • sku_scope — list[str] | "all" — SKUs this mandate governs.
  • pricing.list_price — int — public list price, minor units.
  • pricing.floor_price — int — lowest acceptable price; tagged PRIVATE_UTILITY, never on the wire.
  • pricing.floor_currency — str — currency of the floor.
  • policies.refund_policy — str — canonical policy text or policy id.
  • policies.return_window_days — int — return window length.
  • policies.fulfillment_options — list[str] — offered fulfillment methods.
  • truthfulness.permitted_claims — list[str] — claim-grounding source set.
  • truthfulness.must_not_claim — list[str] — forbidden claims.
  • authority.can_negotiate — bool — pricing role may negotiate.
  • authority.auto_accept_threshold — int — auto-accept at or above, minor units.

GroundedOffer

A concrete committed offer carried by propose_offer / counter_offer.

  • offer_id — str — offer identifier.
  • merchant_id — str — committing merchant.
  • sku_id — str — offered SKU.
  • qty — int — quantity.
  • unit_price — int — price per unit, minor units.
  • fulfillment.method — str — shipping/fulfillment method.
  • fulfillment.eta_days — int — estimated days to delivery.
  • claims — list[str] — subset of OfferMandate.permitted_claims; scored for grounding.
  • expires_at — ts — offer expiry.
  • idempotency_key — str — de-dupe token for the commitment.

MatchCertificate

Platform attestation that a mandate matched an offer truthfully under policy P at time T; VCP's novel object.

  • cert_id — str — certificate identifier; disputes reference it.
  • issued_by — str — platform:aggregator | platform:adjudicator.
  • issued_at — ts — issue timestamp.
  • purchase_mandate_id — str — matched PurchaseMandate.
  • offer_id — str — matched GroundedOffer.
  • verification_policy — str — policy version that was applied.
  • checks_passed.constraint_fit — bool — offer satisfies the mandate's hard_constraints.
  • checks_passed.claim_grounding — bool — offer.claims ⊆ permitted_claims.
  • checks_passed.inventory_available — bool — world.read_inventory true at issue time.
  • checks_passed.reputation_threshold — bool — reputation cleared, if policy demands.
  • signature — str | null — null unless a signed-envelope scenario.

TransactionStateDiff

Materialized once per world.* write; the canonical replay artifact consumed by the eval oracle.

  • diff_id — str — diff identifier.
  • caused_by — str — msg_id of the envelope that triggered the write.
  • applied_at — ts — when the write was applied.
  • table_writes[].table — str — catalog | inventory | orders | ledger | reputation | disputes | rulings.
  • table_writes[].op — str — insert | update | delete.
  • table_writes[].key — dict — primary key of the affected row.
  • table_writes[].before — dict | null — pre-image, null on insert.
  • table_writes[].after — dict | null — post-image, null on delete.
  • invariants_held.atomicity — bool — transaction applied whole or rolled back.
  • invariants_held.idempotency — bool — re-send returned the cached diff.
  • invariants_held.side_partition — bool — permission matrix respected.
  • invariants_held.private_utility — bool — no PRIVATE_UTILITY value leaked.

For the conceptual walkthrough of each object and a worked human-vs-JSON instance, see /developers/objects. For the wire shape and field-level rules of the message that carries every payload, see /developers/envelope.