Provider fidelity is the product. Route paths, required headers, request fields, statuses, errors and signatures must come from the provider's official contract or SDK, not from a convenient internal shape.
#Source precedence
For a provider-facing change, consult sources in this order:
- Imported official specification under
contracts/<provider>/and the matchingdocs/en/fidelity/<provider>.md. - Official SDK when the specification is silent or the SDK's behaviour is what an integration consumes.
- The architecture contract under
.agents/. - Current implementation and tests.
- The web only for information not available above.
If implementation and official contract disagree, implementation is the defect.
#Current contract state
Official OpenAPI snapshots are stored in contracts/mercadopago/mpOrders.json,
contracts/stripe/spec3.json and contracts/paypal/paypalOrders.json /
paypalPayments.json. Each has adjacent .meta.json metadata with source URL,
retrieval date and SHA-256 over the exact downloaded bytes. Runtime validation
is still a hand-written subset, not full OpenAPI validation.
Fidelity limits and confirmed routes live in:
#Explicit import
The Mercado Pago importer is opt-in and allow-listed:
ALLOW_CONTRACT_DOWNLOAD=true npm run contract:import:mercadopago --workspace @payment-emulator/api
It downloads the configured official document, canonicalizes JSON and records a SHA-256 checksum. Contract download is tooling, never part of API or worker runtime. Verify the generated artifacts and attribution before committing them.
#Adding contract coverage
- Store the official document and checksum under
contracts/<provider>/. - Record origin, version/date and license/attribution.
- Derive provider validation without leaking provider fields into the canonical model.
- Add conformance cases and official-SDK checks where possible.
- State unsupported fields/products in the fidelity document.
A checksum proves which document was imported; it does not prove the emulator implements every operation in that document.
The opt-in importer writes canonicalized snapshots to ignored contracts/imported/;
these are separate from the raw-byte audit snapshots above.