# 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 + wallet setup | None by default; optional scoped `X-API-Key` in hardened mode | OpenAPI + contract fixtures + cross-rail smoke matrix + doc drift checks | Canonical runtime API; public routes may return `429 RATE_LIMITED` with `Retry-After` / `retryAfterMs` guidance |
| Skills (`skills/*.md`) | Stable | Reusable agent workflows | N/A | `npm run check:skills` | Agent-agnostic procedural layer |
| 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 (`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-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 tightens runtime enforcement to match the already-documented acknowledge-first partner workflow; clients must acknowledge before marking ready.

## 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.

## Telemetry Contract (Version `telemetry.v1`)

Canonical schema artifact:
- `ops/metrics/telemetry-schema.v1.json`
- Validate with `node scripts/validate-telemetry-schema.mjs`

Surface notes:
- `surface=api` covers request and response usage signals such as onboarding funnel events.
- The current onboarding funnel NDJSON log remains the runtime-specific API subset and still emits `step` / `method` fields; `telemetry.v1` is the versioned contract that downstream ingestion should map onto.
- `surface=docs` covers page views, CTA clicks, and hashed search interactions.
- Raw search text, names, phone numbers, wallet addresses, payment signatures, cookies, IP addresses, and user agents are prohibited.

## Onboarding Funnel Telemetry (Sprint 3)

Local runtime emits onboarding funnel events for:
- `GET /v1/menu` (`step=menu`)
- `POST /v1/orders/quote` (`step=quote`)
- `POST /v1/orders/confirm` (`step=confirm`)
- `GET /v1/orders/:id` (`step=status`)

Default local event log path:
- `${TMPDIR:-/tmp}/pizza-x402/onboarding-funnel-events.ndjson`
- Optional override: `PIZZA_ONBOARDING_FUNNEL_LOG_PATH=/custom/path.ndjson`

Schema (one JSON object per line):

| Field | Type | Notes |
|---|---|---|
| `ts` | ISO-8601 string | Event timestamp |
| `source` | string | Always `pizza-x402-api` |
| `requestId` | string | Fastify request correlation ID |
| `step` | enum | `menu`, `quote`, `confirm`, `status` |
| `method` | string | HTTP verb |
| `route` | string | Route pattern |
| `statusCode` | number | HTTP status for the step |
| `outcome` | enum | `success`, `payment_required`, `error` |
| `paymentMethod` | enum? | `card` or `crypto` when available |
| `quoteId` | string? | Non-PII correlation ID |
| `orderId` | string? | Non-PII correlation ID |
| `errorCode` | string? | API error code (if error payload includes one) |

Privacy guardrails:
- Contact fields, names, phone numbers, wallet addresses, emails, and street addresses are excluded from this telemetry schema.
- Payment signatures, cookies, IP addresses, and raw search text are also excluded from `telemetry.v1`.
- Use `npm run report:onboarding-funnel` to compute counts/drop-off and run a built-in privacy scan.

## 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 `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 (`tests/contracts`, 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.
- 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`