# PR7 API compatibility baseline

## Evidence-bound V2 fixtures

`baseline/schemas/v2/route-response-fixtures.json` covers all 132 paths in
`baseline/extracted/v2_api_routes.txt` exactly once.

| Fixture status | Routes | Meaning |
|---|---:|---|
| `exact` | 1 | `/api/contracts` has a route-specific recorded response (`baseline/raw_api_contracts.txt`). Every observed field is required; additive fields are allowed. |
| `unresolved` | 131 | No route-specific recorded response exists in this repository. No schema has been inferred. |

The two retained well-known response captures are intentionally recorded under
`unmatchedEvidence`: they belong to `/.well-known/agent-card.json` and
`/.well-known/x402.json`, paths not present in the extracted V2 API inventory.
They are not treated as evidence for similarly named `/api/...` paths.

## Generated registry alignment

The generated x402 registry is not falsely presented as the complete V2 route
inventory. `pr7/generated/v2-inventory-alignment.json` records every extracted
path with its registry and response-fixture state. The x402 registry supplies
operational metadata for 82 of 132 inventory paths. For the remaining 50,
`baseline/schemas/v2/route-source-method-evidence.json` freezes the handler
methods from the exact pinned V2 source (55 method-specific rows because five
paths expose multiple methods). The typed inventory gap is therefore zero, but
these entries are explicitly `method-only`, not operational x402 entries.
Six x402 registry paths are absent from the extracted inventory.

Method-only entries contain no inferred request schema, payment/free status,
finality, privacy, idempotency, response status, or response-header contract.
They are intentionally absent from the generated operational OpenAPI document,
which must not imply request/response semantics from a handler export.
`/api/contracts` is the sole method-only path with a route-specific recorded
response fixture, but that evidence remains in the fixture baseline rather
than being promoted to an OpenAPI status contract. All V2 x402 entries expose
`responseSchema: null` and an unresolved fixture status until route-specific
response evidence exists.

## Consumer rule

The TypeScript compatibility checker verifies that existing captured fields and
their JSON types remain present. Object schemas permit additional properties,
which keeps future response fields optional for old consumers. It does not
pretend that an unresolved path has a known response schema.

## V3 response rule

`pr7/compat/v3-envelope.ts` defines the required V3 source-provenance envelope:
`chainId`, `contractAddress`, `protocolVersion`, `contractStatus`, `status`,
`blockNumber`, `blockHash`, `observedAt`, `finality`, `dataSourceErrors`, and
`schemaVersion`, plus `data`.

A healthy response must have concrete source context and data. A source-read
error yields `status: "degraded"`, `data: null`, null provenance fields, a
non-empty `dataSourceErrors` list, and HTTP 503. The V3 status endpoint and V3
SDK pause gate use this rule and therefore fail closed.

The aggregate solvency response carries the same report-level metadata with
null aggregate contract context, while every contract row has concrete
`chainId`, `contractAddress`, `contractStatus`, block context, finality,
observed timestamp, source errors, schema version, and row status. A failed
block or balance read leaves financial fields null and makes the response 503;
it never substitutes zero assets or a zero delta.

## Validation commands

```sh
npm --prefix pr7 run check:api-compat
npm --prefix pr7 run check:registry
npm --prefix pr7 run test:api-compat
npm --prefix pr7 test
npm --prefix pr7 run typecheck
git diff --check
```

## Remaining capture gaps

This repository does not include route-specific HTTP response recordings for
131 inventoried V2 paths, nor HTTP status/header recordings for any V2 route.
The route handlers in the pinned V2 workspace snapshot prove methods, but
static handler exports alone do not establish a consumer response contract.
Completing those fixtures requires recorded equivalent requests/responses
(including paid and failure cases) tied to each exact V2 path, with request
method, URL, status, complete headers, and raw body retained before CI can
enforce schemas or RPC-failure behavior.

`VaultfireTrustAttestation` remains a separate ABI release blocker. It may be
resolved only by the V2 source owner or an authoritative explorer/source
publisher supplying an exact canonical ABI, exact Solidity source closure, or
verified deployed-source response for the listed deployment(s). Bytecode,
selector guesses, and similarly named attestation contracts are explicitly
insufficient; see `baseline/V2_ABI_PROVENANCE.md` and
`legacy/v2/manifest.json`.
