P5: Wire 11 detected-only protocol adapters into kernel dispatch (deferred from P4.K1)

[lexwhiting]

Background

P4.K1 (commit 67a1cfe, 2026-05-01) shipped the public kernel demo at /demo/kernel. The demo is data-driven from protocolRegistry.list() and KERNEL_DISPATCHED_PROTOCOLS, so it grows automatically when kernel dispatch expands.

Today the kernel only settles 3 of the 14 registered protocols end-to-end. The other 11 are detected by protocolRegistry.detect() but kernel.handle() returns the 402 manifest instead of running verify+settle.

Gate: PHASE_1_KERNEL_PROTOCOLS = ['mcp', 'x402', 'mpp'] at packages/mcp/src/kernel.ts:200.

Full triage in docs/phase-reports/P5-kernel-dispatch-expansion-deferred.md.

Why deferred (not bundled into P4.K1)

These are payment protocols. Each kernel dispatch branch directly enables real settlement code in production. Bundling 4+ adapter wirings into the demo PR would have produced a ~1500-line diff across 16+ files, trading reviewability for speed on payment-critical code. Each Tier 1 adapter deserves its own focused PR with its own audit chain.

Triage

Tier 1 — code-only, wirable in a single PR each

Adapters whose verify/settle methods take env-derivable config only (no partner sandbox, no external infra).

• AP2 (Google Agent Payments Protocol 2) — `Ap2ValidateOptions` needs HMAC `signingSecret`. `AP2_SIGNING_SECRET` is already in `turbo.json` build env. Recommended starting point (clearest dependencies, smallest blast radius).
• ACP (Agentic Commerce Protocol) — `AcpValidateOptions` shape; verify if it's purely signature-based or needs a directory lookup
• UCP (Universal Commerce Protocol) — `UcpValidateOptions` shape; same verification needed
• Circle Nano (Circle stablecoin micro-rail) — `CircleNanoValidateOptions`; confirm whether verify uses Circle Mint API (live calls) or only on-chain signature checks

Tier 2 — need partner sandbox access

• Visa TAP — Visa Direct sandbox (apply at developer.visa.com)
• Mastercard VI — Mastercard Send / Click to Pay sandbox
• EMVco — EMVco directory test environment

Tier 3 — need real-world infrastructure

• L402 — LND or Voltage Lightning node + macaroon mint key. Adapter has the validation/settlement primitives in `packages/mcp/src/adapters/l402.ts` and `lightning/voltage.ts`; what's missing is a configured node + the `/api/l402/{verify,settle}` HTTP wrappers
• alipay (Ant Group ACTP) — Ant Group partner contract
• kyapay (Klarna Pay) — Klarna API credentials + agreement
• drain — underlying rail TBD (per adapter docstring this is experimental)

Per-PR contract (apply to every Tier 1 adapter)

For each adapter graduating from "detected" to "settled end-to-end":

1. Add the protocol name to `PHASE_1_KERNEL_PROTOCOLS` at `packages/mcp/src/kernel.ts:200`
2. Add a dispatch branch in `kernel.handle()` (lines 301–330). Most can extend the existing `handleFacilitatorProtocol` branch
3. Add server-side HTTP routes at `apps/web/src/app/api//{verify,settle}/route.ts` that wrap the adapter's `verify`/`settle` methods
4. Integration tests against the new routes; unit tests on the kernel branch; E2E test through `kernel.handle()`
5. Update `KERNEL_DISPATCHED_PROTOCOLS` in `apps/web/src/lib/demo-kernel-config.ts` so the demo reclassifies the adapter from "402-manifest only" to "settled end-to-end"
6. Run the audit chain: spec-diff, hostile (no real money path silently enabled for `demo-sandbox-tool`), tests

Reference implementation for the HTTP wrapper pattern: `apps/web/src/app/api/x402/{verify,settle}/route.ts`.

Files to read first

• `packages/mcp/src/kernel.ts` — especially `handleFacilitatorProtocol` (lines 520–574) for the dispatch contract
• `packages/mcp/src/adapters/.ts` — for the specific adapter's `verify`/`settle` methods + options shape
• `apps/web/src/app/api/x402/{verify,settle}/route.ts` — existing reference HTTP wrapper

Verification before merging each PR

• `npx turbo run test` passes (currently 138 files / 3654 tests after P4.K1)
• `cd apps/web && npx next build` exits 0
• New routes appear in build output

Related

• Tracker doc: `docs/phase-reports/P5-kernel-dispatch-expansion-deferred.md`
• Demo commit: 67a1cfe
• Deferral commit: 82ab568
• In-code TODO: `packages/mcp/src/kernel.ts:200` and `apps/web/src/lib/demo-kernel-config.ts:KERNEL_DISPATCHED_PROTOCOLS`

🤖 Generated with Claude Code