x402x: Add workspace-only v2 packages (core_v2, fetch_v2, hono_v2, express_v2) and complete x402 v2 migration behind stable v1 outputs

[jolestar]

We plan to upgrade x402x’s x402 dependency to official x402 v2, but the migration is large and should be delivered incrementally without breaking existing v1 consumers (including the showcase and facilitator).

This issue tracks the agreed delivery plan and package-splitting strategy.

Context

• Current repo depends on x402 via a patched alias (x402: npm:@x402x/x402@...) while official v2 is published as @x402/*.
• The main risk is not package-name conflicts, but mixing v1/v2 types and protocol semantics (headers, network IDs, Payment* structures) inside the same TypeScript package.
• Upstream x402 v1 compatibility is layered (core/http client is version-aware; framework wrappers have legacy/*), so we’ll be explicit about boundaries in x402x as well.

Decisions (confirmed)

1. Create @x402x/core_v2 that re-exports official v2 types from @x402/core/types.
2. v2 packages are workspace-only (private: true), not published to npm during migration.
3. No changes to existing public packages and runtime behavior for now:
   • @x402x/core, @x402x/fetch, @x402x/hono, @x402x/express
   • showcase and facilitator remain on v1 behavior until v2 is complete.
4. New v2 packages participate in CI (pnpm -r --filter "@x402x/*" test).

Proposed package split (migration period)

v1 (unchanged)

• @x402x/core continues to depend on patched x402 and can import x402/*.
• @x402x/fetch, @x402x/hono, @x402x/express continue using v1 semantics and dependencies.
• Showcase/facilitator keep current behavior (headers etc.).

v2 (new, workspace-only)

• @x402x/core_v2:
  • depends only on @x402/* (at least @x402/core) + viem
  • MUST NOT depend on patched x402.
  • provides helper for x402x-router-settlement extension and structured PaymentRequirements.extra.
• @x402x/fetch_v2:
  • thin wrapper over @x402/fetch
  • registers a custom x402x exact-EVM SchemeNetworkClient to support router settlement (commitment + EIP-712) and delegates to official exact EVM otherwise.
• @x402x/hono_v2 / @x402x/express_v2:
  • thin wrappers over @x402/hono / @x402/express
  • implement/override SchemeNetworkServer.enhancePaymentRequirements to inject extension + extra and support eip155:* wildcard.
• (optional) a v2 facilitator mechanism package can be added later using the same separation.

Guardrails

• Enforce import boundaries with lint:
  • *_v2 packages: forbid x402/* imports.
  • v1 packages: forbid @x402/* imports.

Milestones (incremental)

0. Add @x402x/core_v2 (private) + re-export @x402/core/types; implement x402x-router-settlement helpers and extra utilities.
1. Add @x402x/fetch_v2 (private): wrapper over @x402/fetch + custom x402x exact-EVM client scheme.
2. Add @x402x/hono_v2 and @x402x/express_v2 (private): wrapper over official middleware + custom server scheme.
3. Implement v2 router settlement mechanism in facilitator (SchemeNetworkFacilitator.verify/settle calling SettlementRouter).
4. After v2 feature-complete: switch public @x402x/* default implementations to v2 and remove v1 patch/alias + clean docs.

Testing expectations

• Add v2 e2e coverage (client/server/facilitator, incl. settlement) within the new v2 packages.
• Keep CI green for both v1 and v2 workspace-only packages throughout.

Reference

• docs/x402x-v2-plan.md (updated with this plan and decisions).

[jolestar]

Created sub-issues for the agreed 6-step roadmap (intended execution order):

1. Subtask 1: Add @x402x/core_v2 foundation (commitment/networks/hooks/abi) + v1/v2 import guardrails #95 — core_v2 foundation (commitment/networks/hooks/abi) + v1/v2 import guardrails
2. Subtask 2: core_v2: Implement x402x-router-settlement extension + PaymentRequirements.extra helpers #92 — core_v2: router-settlement extension + PaymentRequirements.extra helpers
3. Subtask 3: Add @x402x/fetch_v2 (private) wrapping @x402/fetch with router-settlement exact-EVM client scheme #91 — fetch_v2: wrap @x402/fetch + custom exact-EVM client (router settlement)
4. Subtask 4: Add @x402x/hono_v2 and @x402x/express_v2 (private) wrapping official middleware with custom server scheme #94 — hono_v2 + express_v2: wrap official middleware + custom server scheme
5. Subtask 5: Add workspace-only facilitator_v2 package implementing SchemeNetworkFacilitator.verify/settle via SettlementRouter #93 — facilitator_v2 mechanism: SchemeNetworkFacilitator.verify/settle via SettlementRouter
6. Subtask 6: Add v2 mock E2E contract tests (PAYMENT-* headers, extensions echo, eip155:* wildcard, router settlement params) #90 — v2 mock E2E contract tests (PAYMENT-* headers, extensions echo, eip155:* wildcard, router settlement params)