# V3 x402 reconciliation handoff — 2026-08-25

## Scope and source authority

Work is additive in `pr7/**` and `repos/theloopbreaker-site/app/api/v3/**`, plus the website release gate. The authoritative recovery inputs were `/home/user/workspace/x402_history_recovery_20260825.md` and `.json`, together with preserved V2 artifacts. No V2 handler, V2 ABI, V2 manifest, or deployed-address record was edited.

`recovered-97-public-x402-identities.json` preserves the evidence qualification: the 86 core and two well-known identities are exact recovered exports; the eight Solana paths are exact source-only inventory paths with read/receive method classification; and the bridge is exact handler evidence with high-confidence reconciliation rather than a recovered single 97-row discovery file.

## Resulting matrix

`v2-v3-route-disposition-matrix.json` uses schema `vaultfire.v2-v3-x402-route-disposition.v2`.

| Inventory | Count | Treatment |
|---|---:|---|
| Public identities | 97 | one row per exact `METHOD path`, with evidence and a V3 disposition |
| Core `/api/x402/*` | 86 | recovery-backed exact identities |
| `/api/solana/*` | 8 | source-only inventory, no invented handler/deployment evidence |
| `GET /api/agent/bridge` | 1 | retired because cross-chain trust data cannot affect V3 routing |
| Well-known | 2 | V3 discovery wrappers only |
| V2 source routes | 132 | separate immutable `v2SourceRouteDispositions` inventory |

V3 disposition totals are: 1 implemented additive handler, 8 safe compatibility wrappers, 51 blocked pending V3 dependency/evidence, and 37 retired for safety. Every public row includes a precise reason, activation evidence requirement, `v2Fallback: forbidden`, a non-enabled payment/settlement label, and a no-listing-ID Bazaar label.

## Additive V3 routes

The generated registry contains eight V3 read-only routes. None has a price, payee, `accepts`, Bazaar eligibility, or a live deployment claim:

- `/api/v3/protocol/solvency` and `/api/v3/protocol/status` return static `not-ready` source/deployment boundaries.
- `/api/v3/x402/discovery` publishes static availability and mission-boundary labels.
- `/api/v3/x402/challenge-status` truthfully says `challengeAvailable: false`, `paymentAccepted: false`, and `listingId: null`.
- `/api/v3/solana/health` is a static source-only readiness response; it does not call RPC/indexer services.
- `/api/v3/x402/receipts/:requestId` has an isolated fail-closed receipt-read boundary.
- The mandate and partnership-action routes remain callable only to return an explicit `503 v3_payment_challenge_unavailable`; no payment header/body is parsed, no 402 is issued, and no write is executed.

The exact existing release flag is still required. Middleware now also gates `/api/v3/solana/:path*`.

## Evidence and safety gates still required

Do not enable payment, settlement, writes, or dynamic contract reads until each proposed route has all of the following independently reviewed evidence:

1. real V3 deployment/address and ABI evidence;
2. V3 request/resource/method binding and durable duplicate/replay protection;
3. durable receipt storage with canonical-chain observation, expiry, reorg, and finality policy;
4. route-specific read schema/data-source evidence and a static security review; and
5. a mission-boundary review showing no behavioral, flourishing, reputation, loyalty, quality, belief, biometric, profiling, or surveillance-derived input affects custody, access, eligibility, pricing, slashing, settlement, disputes, or routing.

Bazaar metadata is not a listing receipt. The V3 candidate count is intentionally zero; no listing IDs, payment receipts, deployment claims, or live indexing claims were created.

## Regression coverage

- 97/97 identity coverage and 132 separate V2 source-route dispositions.
- exact V2 action-handler hash checks and no protected V2 source/ABI/manifest/deployed-record diff.
- exact release flag, V3-only allowlist, static safe responses, and failed payment/write paths.
- no V3 price/payee/accepts or V3 Bazaar candidate resources.
- durable receipt-store duplicate request binding, payment/authorization/nonce replay, transaction replay, expiry, and reorg behavior.

## Commands and results

All executed without installs, wallets, paid endpoints, deploys, pushes, commits, or RPC writes:

```text
cd pr7 && npx vitest run                                  PASS (17 files, 103 tests)
cd pr7 && npm run typecheck                               PASS
python3 pr7/compat/build-v2-v3-route-disposition-matrix.py --check  PASS
python3 pr7/compat/build-v2-v3-compatibility-matrix.py --check       PASS
SOURCE_DATE_EPOCH=0 python3 pr7/registry/build_full_registry.py      PASS
python3 pr7/registry/validate_bazaar_v2.py                           PASS
```

`npm test` is blocked only at its final clean-git generated-artifact assertion because this handoff intentionally leaves the regenerated artifacts uncommitted. The builder/validator and direct locked test suite pass.
