# Agent Compatibility Matrix

This matrix summarizes the currently supported agent integration surfaces and their maturity.

## Transport / Interface Matrix

| Interface | Status | Scope | Auth | Validation | Notes |
|---|---|---|---|---|---|
| Direct HTTP (`/v1/*`) | Stable | Public ordering + future/experimental x402 wallet setup | None by default; optional scoped `X-API-Key` in hardened mode | OpenAPI + `internal/http/router_test.go` + Stripe card smoke plus experimental x402 compatibility checks | Canonical runtime API; public routes may return `429 RATE_LIMITED` with `Retry-After` / `retryAfterMs` guidance |
| Skills guidance (`docs/public/skills.md`) | Stable | Reusable agent workflows | N/A | `npm run check:skills` | Published agent guidance lives in the docs authority; implementation/tooling lives outside the docs repo |
| Official MCP repo (`pizzax402/pizzax402-mcp`) | Stable | Public tools + partner tools | Partner tools use `PIZZA_X402_PARTNER_API_KEY` | Standalone MCP repo build + stdio/http e2e tests against `pizza-x402` | Official builder install path; canonical semantics still come from `pizza-x402` |
| MCP HTTP (Streamable HTTP) | Experimental / usable | Same tools as stdio | Same as stdio | HTTP smoke e2e (`mcp-http-transport.spec.ts`) | Good for remote/local HTTP clients |
| A2A Gateway (REST + JSON-RPC subset) | Experimental / usable | Agent Card + REST task lifecycle + JSON-RPC + SSE streaming + context correlation | None (public ordering ops) | A2A package unit + e2e + conformance fixture tests | Sprint 6 subset implemented; more conformance/streaming scope planned |
| ERC-8004 Bridge (`pizza-x402-api/packages/trustless-agent-bridge`) | Experimental / usable | Off-chain trust/discovery/feedback/validation artifacts + signed metadata exports | Local secret for optional JWS signing | Bridge package unit/snapshot/schema/CLI tests | Sprint 8 off-chain prototype implemented; onchain registries remain out of scope |
| Agent Evals (`packages/agent-evals`) | Experimental / usable | Deterministic scenario checks + transcript goldens | None | Evals package build + tests | Sprint 9 package validates core flows and AGENTS transcript markers |

## Recent Contract Notes

- 2026-04-23: Locale contracts now separate dashboard/platform UI language from merchant-authored content language. `PlatformLocale` remains restricted to `en`/`fr` for merchant dashboard preferences and platform copy, while `ContentLocale` accepts arbitrary valid BCP 47 tags for merchant source content, storefront publication, translations, and public locale URLs. Compatibility note: accepted pre-launch breaking locale-semantics hardening; public clients should request explicit content locales when needed, treat `Accept-Language` only as suggestion metadata, and consume resolved customer-facing copy rather than relying on raw translation maps.
- 2026-03-29: Public merchant identity now uses immutable `merchantHandle`, while internal merchant/admin/operator identity uses UUID `merchantId`. Compatibility note: accepted breaking pre-launch contract rewrite; public bootstrap routes moved to `/v1/merchants/{merchantHandle}/*`, request-bound ordering context moved to `X-Merchant-Handle`, and authenticated merchant/partner payloads keep exposing internal UUIDs where operational tooling needs them.
- 2026-03-17: `GET /v1/menu` now returns additive `itemType` for every item plus optional `imageUrl` for menu artwork, while pizza menu records persist a structured `artworkInput` contract behind the scenes. Compatibility note: additive menu response expansion only; existing clients remain compatible, while storefronts can render stable public SVG artwork URLs without calling the generator directly.
- 2026-03-16: Added founder-grade activation visibility (`GET /partner/merchant-activation`) plus canonical Merchant Console routes for workspace and QR distribution (`GET|PATCH /merchant/workspace`, `GET /merchant/qr-kit`). Compatibility note: additive partner/merchant control-plane expansion only; founder visibility stays on the internal/partner surface, while the authenticated merchant app can move from Launchpad-only route names into stable console contracts.
- 2026-03-16: Added self-serve merchant activation routes for the authenticated merchant app: `POST /merchant/signup`, `GET|PATCH /merchant/launchpad*`, and owner-authenticated `GET|POST /merchant/payment-hub/stripe-connect*`. Compatibility note: additive merchant control-plane expansion only; the public site remains a handoff surface while the authenticated merchant app becomes the canonical owner/staff surface.
- 2026-03-16: `POST /v1/orders/quote` now requires `contact.email`, and successful paid-order creation triggers receipt delivery through the configured provider so the customer receives a bookmarkable `Order Pass` recovery link. Compatibility note: additive customer-recovery completion only; no customer account or separate recovery token is introduced.
- 2026-03-16: Added cookie-backed merchant auth/session routes, merchant-managed member administration, canonical `/merchant/order-desk/*` routes, partner first-owner bootstrap, and a `paid -> acknowledged -> ready -> fulfilled` pickup lifecycle with default-visible pickup codes. Compatibility note: additive control-plane expansion only; public order lookup now returns `pickupCode` and can surface `readyAt`, while legacy `/partner/orders/*` routes remain temporarily supported for fallback tooling.
- 2026-03-11: `POST /v1/orders/confirm` now accepts `paymentSignature` in the JSON body in addition to the legacy `PAYMENT-SIGNATURE` header, and invalid x402 proofs can return structured `details` fields for storefront recovery UX. Compatibility note: additive confirm-request support only; existing header-based clients remain compatible, while browser storefronts can use body-based proof submission and reason-aware payment recovery messages.
- 2026-03-10: Established the extracted `pizza-x402-api` Go runtime foundation (`cmd/api`, `internal/*`, Postgres/sqlc store, and Cloud Run delivery assets) plus CI/package wiring for the new backend repo. Compatibility note: repo/runtime foundation only; the published public contract and generated documentation are refreshed in the stacked follow-up contract/docs PRs.
- 2026-03-10: Merchant bootstrap now includes `walletSetupUrl`, and storefront-facing URLs are derived from `PUBLIC_BASE_URL` so quote/payment helper payloads stop leaking `localhost` outside local development. Compatibility note: additive merchant bootstrap field plus canonical URL normalization; storefront consumers should prefer bootstrap-provided URLs over hardcoded path joins.
- 2026-04-09: Axel (`au-comptoir-a-patons`) now uses Stripe Checkout Sessions plus Accounts v2 webhook reconciliation for the card branch, proving `quote -> checkoutSession -> paid order` in EUR. Compatibility note: card clients must follow hosted Checkout plus `GET /v1/orders/checkout-sessions/{checkoutSessionId}` instead of assuming embedded PaymentIntent confirmation.
- 2026-03-09: Added the first canonical merchant bootstrap endpoints plus request-bound merchant transport for shared storefront work, while keeping card explicitly secondary to the Base/USDC direction in contract wording. Compatibility note: this historical additive slice was later superseded by the 2026-03-29 `merchantHandle` contract rewrite and the 2026-04-30 Stripe-only launch reset.
- 2026-03-09: `openapi.yaml` now scopes the published contract to `/v1/*` and `/partner/*`, removing `/internal/*` operational routes from the public spec and exported docs bundle. Compatibility note: public contract became safer and more focused; no public endpoint behavior changed.
- 2026-03-08: Merchant-context review now runs through `docs/public/merchant-context-parity-checklist.md`. Compatibility note: the checklist centralizes shared merchant identifier semantics and the required merchant configuration field list for API, MCP, and storefront work; no transport or schema changed.
- 2026-03-08: OpenAPI `info.description` now describes the HTTP surface as a merchant-scoped ordering API instead of a single-pizzeria pilot. Compatibility note: descriptive metadata only; no endpoint, method, or schema changes.
- 2026-03-07: `GET /partner/orders/api` now includes `availableActions` on each `PartnerOrder`, so fallback merchant tooling can render the next legal operator step without duplicating workflow rules client-side.
- 2026-03-07: `POST /partner/orders/{id}/fulfill` now rejects direct `paid -> fulfilled` transitions. Compatibility note: this tighter legacy fallback rule has now been superseded by the canonical `paid -> acknowledged -> ready -> fulfilled` lifecycle; compatibility callers can still fulfill from `acknowledged`, but only because the runtime upgrades them through `ready` internally.

## Merchant Context Parity Gate

- Canonical checklist: `docs/public/merchant-context-parity-checklist.md`
- MCP and storefront-facing compatibility notes should reference that checklist instead of redefining merchant configuration requirements.
- Merchant-context-sensitive interface work should not expand until the checklist still passes for API, MCP, and storefront assumptions.

## MCP Client Notes

| Client Type | Recommended Transport | Notes |
|---|---|---|
| Local coding agents (Codex / Claude Code style) | stdio | Lowest setup friction, no HTTP listener required |
| Generic local MCP host | stdio | Clone `pizzax402-mcp` and use `npm run dev`; core maintainers can still run `cd ../pizza-x402-api && npx tsx packages/mcp-server/src/index.ts` |
| Remote/dev-stack MCP client | Streamable HTTP | Use `npm run dev:http` in `pizzax402-mcp` and point the client to `/mcp` |

## A2A Client Notes (Sprint 6 Subset)

| Client Type | Recommended Interface | Notes |
|---|---|---|
| Agent orchestration prototype | HTTP+JSON/REST | Use `/.well-known/agent-card.json` + `/a2a/messages` + `/a2a/tasks/*`; SSE supported for task streams |
| JSON-RPC-capable agent host | HTTP+JSON/REST + JSON-RPC | Use `POST /a2a/jsonrpc` with `A2A-Version: 0.2`; methods: `message/send`, `tasks/get|list|cancel` |
| Production interop pilot | Start REST, add JSON-RPC selectively | Sprint 6 subset is usable; JSON-RPC streaming/multiturn standards breadth still staged |

## Versioning Policy (MCP Surface)

- Tool names are treated as stable once released (`get_menu`, `create_quote`, etc.).
- Additive fields in tool `structuredContent` are allowed.
- Official builder-facing MCP releases ship from `pizzax402-mcp`, but the canonical semantics and compatibility rules remain anchored in `pizza-x402`.
- Merchant-context-sensitive MCP changes must stay aligned with `docs/public/merchant-context-parity-checklist.md`.
- Breaking input/output changes require:
  1. OpenAPI and `AGENTS.md` updates (if underlying API changed)
  2. `docs/public/mcp.md` release note
  3. `HISTORY.md` entry documenting MCP surface impact
  4. Updated MCP repo tests (`stdio` and `HTTP` if applicable)
  5. A compatibility statement tying the MCP repo release back to the matching `pizza-x402` contract

## Agent Integration Change Management (Sprint 9)

For agent-facing changes (HTTP, skills, MCP, A2A, trustless bridge, evals):

1. Update `openapi.yaml` and `AGENTS.md` if public behavior changed
2. Update impacted `docs/public/*` guides and quickstarts
3. Update tests/evals (`internal/http/router_test.go`, package e2e tests, `packages/agent-evals`)
4. Add a `HISTORY.md` entry describing the integration impact and include `Semver impact: none|patch|minor|major (...reason...)`
5. Run `npm run doctor:agent`, `npm run release:check`, and affected package tests
6. If merchant context is touched, update or explicitly reaffirm `docs/public/merchant-context-parity-checklist.md` in the same change

## OpenAPI Contract Governance Gate (Sprint 2)

When a PR modifies `openapi.yaml`:

1. Run `npm run check:openapi-contract-diff` (or `node scripts/check-openapi-contract-diff.mjs --base main`) before opening the PR.
2. Ensure both `HISTORY.md` and `docs/public/compatibility-matrix.md` are updated in the same PR.
3. Review additive vs breaking classification in the JSON report and document impact in PR notes.
4. Treat gate failures as release blockers for agent-facing API changes.

## Release Governance Gate (Sprint 06)

When a PR modifies package surfaces, public contracts, or release-process checker scripts:

1. Run `npm run check:release-governance` (or `node scripts/check-release-governance.mjs --base main`) before opening the PR.
2. Update `HISTORY.md` in the same branch with a line formatted as `Semver impact: none|patch|minor|major (...reason...)`.
3. Update both `docs/public/compatibility-matrix.md` and `docs/public/contract-parity.md` in the same branch.
4. Use `node scripts/check-release-governance.mjs --files package.json` to simulate the missing-changelog failure path locally when validating remediation instructions.
5. Rerun `npm run smoke:quickstart` when payment-affecting changes land so release review still has a compact card and onchain paid-order signal.
6. Treat governance-gate failures as release blockers even if the runtime test suite is otherwise green.

## HTTP Runtime Notes

- Public `/v1/*` routes now expose a documented `429 RATE_LIMITED` envelope when burst budgets are exceeded.
- Public `/v1/*` routes can also require scoped `X-API-Key` authentication when `PUBLIC_API_AUTH_MODE=api-key`; open mode remains the default for local/demo flows.
- Hardened public keys are merchant-bound and scope-limited so production deployments do not need to reuse partner/admin credentials on the public surface.
- Shared storefront implementations can bootstrap merchant identity via `/v1/merchants/{merchantHandle}/info|legal|contact-details` and currently forward merchant context on ordering APIs with `X-Merchant-Handle` until customer URL topology is finalized.
- Merchant/staff browser surfaces now use same-site cookie sessions on `/merchant/*`; state-changing routes rely on origin checks plus `HttpOnly` session cookies instead of bearer tokens or localStorage auth.
- Operational `/internal/*` routes remain intentionally out of scope for public contract artifacts and public docs exports.
- Agents should pause retries until the later of the `Retry-After` header or JSON `retryAfterMs` delay.
- Partner/operator and webhook routes also use separate limiter budgets so public ordering traffic is not penalized by internal or callback spikes.

## Current MCP Toolset (Sprint 4)

Public tools:
- `get_menu`
- `create_quote`
- `confirm_order`
- `get_order_status`
- `get_wallet_setup`

Partner tools:
- `list_partner_orders`
- `ack_order`
- `fulfill_order`