# Agent Contract Parity Matrix

This document tracks the canonical agent-facing contract across runtime behavior, `openapi.yaml`, and `AGENTS.md`.

Source-of-truth authority: `docs/adr/ADR-0002-api-docs-source-of-truth.md`.

## Guardrails

- Runtime contract examples and representative fixtures are validated in `tests/contracts/openapi-runtime.spec.ts`
- Cross-doc drift markers are checked by `npm run check:agent-doc-drift` (script: `scripts/check-agent-doc-drift.mjs`)
- Runtime/OpenAPI endpoint drift is checked by `npm run check:openapi-endpoint-drift` (script: `scripts/check-openapi-endpoint-drift.mjs`)
- Release-governed diffs are checked by `npm run check:release-governance` (script: `scripts/check-release-governance.mjs`)
- The narrow paid-order release signal is checked by `npm run smoke:quickstart`, which now prints a compact card and onchain smoke matrix
- Public MCP repo packaging and install guidance must stay aligned with the canonical MCP semantics documented in `pizza-x402`
- Merchant-context changes across API, MCP, and storefront planning must pass `docs/public/merchant-context-parity-checklist.md`
- `docs/public/ia.json` is generated and validated via `node scripts/docs/build-ia-manifest.mjs --check` for deterministic docs inventory parity
- CI runs build, contract checks, doc drift checks, and tests before merge
- Telemetry contract version `telemetry.v1` is defined in `ops/metrics/telemetry-schema.v1.json` and validated locally with `node scripts/validate-telemetry-schema.mjs`

## Recent Parity Notes

- 2026-03-09: `openapi.yaml` now excludes `/internal/*` operational routes from the published public spec, and the top-level description matches the merchant-scoped public HTTP surface. Parity note: public contract presentation changed; `/v1/*` and `/partner/*` behavior remains unchanged, and `AGENTS.md` stays aligned.
- 2026-03-08: Added `docs/public/merchant-context-parity-checklist.md` as the canonical merchant-context review gate for API, MCP, and storefront work. Parity note: documentation/governance only; no runtime endpoint or schema behavior changed.
- 2026-03-08: `openapi.yaml` top-level `info.description` now describes the public HTTP surface as a merchant-scoped ordering API instead of a single-pizzeria pilot. Parity note: descriptive metadata only; no runtime endpoint or schema behavior changed, and `AGENTS.md` remains aligned.

## Merchant Context Parity Gate

Canonical checklist:
- `docs/public/merchant-context-parity-checklist.md`

Use the checklist whenever a change touches:
- merchant identifier semantics
- merchant-bound auth or quote/confirm safety wording
- public examples that show merchant identity
- storefront assumptions that depend on API or MCP merchant context

## Telemetry Contract

Canonical telemetry schema:
- Version: `telemetry.v1`
- Artifact: `ops/metrics/telemetry-schema.v1.json`
- Validation: `node scripts/validate-telemetry-schema.mjs`

Privacy guardrails:
- Allowed correlation fields stay limited to non-PII handles already present in the public contract (`quoteId`, `orderId`, `requestId`).
- Docs search and docs interaction telemetry must use enumerated or hashed fields such as `ctaId` and `queryHash`, not raw free-form user text.
- Names, phone numbers, wallet addresses, payment signatures, cookies, IP addresses, and user agents are prohibited fields for this telemetry contract.

## Public Endpoint Parity Matrix

| Endpoint | Runtime behavior (source) | OpenAPI contract | AGENTS.md coverage | Notes |
|---|---|---|---|---|
| `GET /v1/menu` | `src/server.ts` (`/v1/menu`) | `Menu` schema | `get_menu` tool | Menu remains USDC-priced for item base pricing |
| `GET /v1/wallet-setup` | `src/server.ts` (`/v1/wallet-setup`) | `WalletSetupGuide` schema | `get_wallet_setup` tool | Dynamic `resources.thisEndpoint` URL |
| `POST /v1/orders/quote` | `src/server.ts` (`QuoteRequest`, quote handler) | `QuoteRequest`, `QuoteResponse` | `create_quote` tool | Hybrid payment response includes `availablePaymentMethods`, `walletSetupUrl`, `paymentInstructions` |
| `POST /v1/orders/confirm` | `src/server.ts` (card + crypto branches) | `ConfirmOrderRequest`, `ConfirmOrderResponse`, `PaymentRequired` | `confirm_order` tool | `200` uses `oneOf` for card intent / card pending / paid order |
| `GET /v1/orders/{id}` | `src/server.ts` (`/v1/orders/:id`) | `Order` schema | `get_order_status` tool | PUBLIC_AGENT-safe PII stripping in `contact` |

## Partner Endpoint Parity Matrix

| Endpoint | Runtime behavior (source) | OpenAPI contract | Notes |
|---|---|---|---|
| `GET /partner/orders/api` | `src/server.ts` (`/partner/orders/api`) | `PartnerOrdersResponse` | Includes `paymentMethod` and `availableActions` for fallback ops tooling |
| `POST /partner/orders/{id}/ack` | `src/server.ts` | `OrderAcknowledged` | Auth required (`X-API-Key`) |
| `POST /partner/orders/{id}/fulfill` | `src/server.ts` | `OrderFulfilled` | Auth required (`X-API-Key`) |

## Drift Prevention Rules

1. Update runtime + `openapi.yaml` + `AGENTS.md` in the same change for agent-facing fields.
2. Add/refresh fixtures in `tests/contracts/fixtures/` for every new public response variant.
3. Keep `docs/public/examples/order-flow.md` aligned with actual payment modes (card and crypto branches).
4. Treat CI failures in `openapi-runtime.spec.ts`, `check-agent-doc-drift`, `check:openapi-endpoint-drift`, or `check:openapi-contract-diff` as release blockers for agent-facing changes.
5. When adding/moving/removing docs pages in `docs/public/**`, regenerate `docs/public/ia.json` and include it in the same change.
6. Downstream generation may consume `docs/public/ia.json` as an allowed source alongside `AGENTS.md` and `openapi.yaml`.
7. When release-governed files change, update `HISTORY.md`, `docs/public/compatibility-matrix.md`, and `docs/public/contract-parity.md` together, and add `Semver impact: none|patch|minor|major (...reason...)` to the new `HISTORY.md` entry.
8. When the official MCP install path changes, update `docs/public/mcp.md`, MCP quickstarts, and any public website docs that name the official repo.
9. Do not duplicate the required merchant configuration field list in other docs; reference `docs/public/merchant-context-parity-checklist.md`.