feat(ruby): pay-kit v2 unified gate API + module restructure

.github/workflows/ruby.yml

@@ -44,3 +44,55 @@ jobs:
           name: surfpool-reports-ruby
           path: ruby/target/surfpool-reports/
           if-no-files-found: ignore
+
+  interop-ruby:
+    name: "Interop: Ruby PayKit server (dual protocol)"
+    needs: test-ruby
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v5
+        with:
+          package_json_file: package.json
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: typescript/pnpm-lock.yaml
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: ruby
+      - name: Install TypeScript workspace
+        working-directory: typescript
+        run: pnpm install --frozen-lockfile
+      - name: Build TypeScript package
+        working-directory: typescript
+        run: pnpm --filter @solana/mpp build
+      - name: Install interop harness
+        working-directory: harness
+        run: pnpm install --frozen-lockfile
+      - name: Typecheck interop harness
+        working-directory: harness
+        run: pnpm typecheck
+      # Dual-protocol proof: one e2e run drives MPP charge scenarios
+      # (typescript client) and x402 exact (rust-x402 client) against
+      # the same ruby adapter binary. The harness's interopEnv exposes
+      # X402_INTEROP_* shadows alongside MPP_INTEROP_* (same surfpool,
+      # same funded keypairs) and stamps every scenario with
+      # PAY_KIT_INTEROP_PROTOCOL so the dual-protocol adapter binds the
+      # right protocol per scenario without relying on env namespace
+      # probing. ts-x402 is intentionally excluded - it is a wire-only
+      # fixture whose payload omits the on-chain transaction, so it can
+      # only pair against the matching wire-only ts-x402 server, not a
+      # real settle server.
+      - name: Run interop smoke (mpp charge + x402 exact)
+        working-directory: harness
+        env:
+          MPP_INTEROP_CLIENTS: typescript
+          MPP_INTEROP_SERVERS: ruby,typescript
+          MPP_INTEROP_INTENTS: charge,x402-exact
+          X402_INTEROP_CLIENTS: rust-x402
+          X402_INTEROP_SERVERS: ""
+        run: pnpm exec vitest run test/e2e.test.ts --testNamePattern "ruby" --testTimeout 180000

.gitignore

@@ -34,3 +34,5 @@ harness/go-client/go-client
 mpp-sdk-self-learning/
 .build/
 go/coverage.out
+notes/codex-review/
+notes/codex-review-*.md

harness/README.md

@@ -123,6 +123,55 @@ Use these environment variables to filter the active matrix:
 - `MPP_INTEROP_INTENTS=charge`
 - `MPP_INTEROP_SCENARIOS=charge-basic,charge-split-ata,charge-network-mismatch,charge-cross-route-replay`
 
+### x402 exact intent
+
+A second intent, `x402-exact`, exercises the canonical x402 `exact` scheme
+against the Rust spine in `rust/crates/x402/src/bin/interop_{client,server}.rs`.
+The TypeScript reference adapters live at
+`src/fixtures/typescript/exact-{client,server}.ts` and share the same
+harness contract as the Rust spine: identical `X402_INTEROP_*` env vars,
+identical `PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` headers, identical
+ready / result JSON shapes. The TS reference fixture carries a stub
+credential payload (challenge id + resource) and is paired against the
+TS reference server in the default matrix; the Rust spine is paired
+against itself. As language adapters that carry a real Solana
+PaymentProof land, they expand the matrix by registering under
+`intents: ["x402-exact"]` in `implementations.ts`.
+
+Env vars consumed by both roles:
+
+- `X402_INTEROP_RPC_URL`, `X402_INTEROP_NETWORK`, `X402_INTEROP_MINT`
+- `X402_INTEROP_PAY_TO`, `X402_INTEROP_PRICE`
+- `X402_INTEROP_FACILITATOR_SECRET_KEY`
+
+Server-only:
+
+- `X402_INTEROP_EXTRA_OFFERED_MINTS` (CSV of additional mint addresses)
+
+Client-only:
+
+- `X402_INTEROP_TARGET_URL`
+- `X402_INTEROP_CLIENT_SECRET_KEY`
+- `X402_INTEROP_PREFER_CURRENCIES` (CSV of preferred currencies)
+
+Run the x402 matrix slice:
+
+```bash
+X402_INTEROP_MATRIX=1 \
+X402_INTEROP_RPC_URL=http://127.0.0.1:8899 \
+X402_INTEROP_MINT=... X402_INTEROP_PAY_TO=... \
+X402_INTEROP_CLIENT_SECRET_KEY='[...]' \
+X402_INTEROP_FACILITATOR_SECRET_KEY='[...]' \
+pnpm test x402-exact.e2e.test.ts
+```
+
+Cross-server portability and idempotent-resubmit scenarios are gated
+separately:
+
+```bash
+X402_INTEROP_CROSS_SERVER=1 pnpm test cross-server-scenarios.test.ts
+```
+
 The current scenario set covers only the `charge` intent. It includes a basic
 payment, a split payment that requires the server fee payer to create the split
 recipient ATA, a negative network-mismatch payment, and a cross-route replay