@agenttrust-sdk/mcp 0.2.6 → 0.3.0

package/dist/embedded-docs/integration-guides/capability-namespaces.mdx

@@ -1,15 +1,142 @@
 ---
 title: Capability namespaces
-description: Naming and hashing convention for validation capabilities.
+description: Register a new namespace, derive its hash, gate against it from PolicyVault. Plus how the v1 sybil-resistance model devolves trust to PolicyVault's accepted_attestors[].
 ---
 
-`In progress`
+Capability namespaces are the names PolicyVault gates against in `RequireValidation`. Each namespace is identified on chain by `SHA-256(name_utf8)` — that 32-byte hash is what `PolicyAccount.required_capability_hash` stores and what the `X-Capability-Required` x402 response header carries.
 
-Capability namespaces let facilitators ask for a specific validation artifact without coupling the payment route to one attestor. The ValidationRegistry stores the namespace and the attestation PDA stores the capability hash.
+Source: [`programs/validation-registry/src/instructions/register_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/register_namespace.rs). State: [`state/capability_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/capability_namespace.rs).
 
-| Source | Path |
-| --- | --- |
-| namespace state | [`programs/validation-registry/src/state/capability_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/capability_namespace.rs) |
-| register instruction | [`programs/validation-registry/src/instructions/register_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/register_namespace.rs) |
-| x402 header | [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts) |
+## Register a namespace
 
+```ts
+import { Keypair, PublicKey, sendAndConfirmTransaction, Transaction } from "@solana/web3.js";
+import {
+  buildRegisterNamespaceIx,
+  computeCapabilityHash,
+  loadValidationRegistry,
+  makeProvider,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+} from "@agenttrust-sdk/trustgate";
+
+const creator = Keypair.fromSecretKey(/* funded devnet keypair */);
+const provider = makeProvider({
+  rpcUrl: "https://api.devnet.solana.com",
+  wallet: creator,
+});
+
+const validationRegistry = await loadValidationRegistry(
+  provider,
+  DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry,
+);
+
+const name = "my-org.attestation.v1";          // ≤ 32 bytes; min 3; no ':' allowed
+const version = "v1";                           // ≤ 16 bytes
+const schemaUri = "https://my-org.example/schemas/attestation.v1.json";
+
+const namespaceHash = computeCapabilityHash(name);  // SHA-256(name)
+
+const ix = await buildRegisterNamespaceIx({
+  program:        validationRegistry,
+  creator:        creator.publicKey,
+  namespaceHash,
+  name,
+  version,
+  schemaUri,
+});
+
+const tx = new Transaction().add(ix);
+const sig = await sendAndConfirmTransaction(provider.connection, tx, [creator]);
+console.log(`Namespace registered: ${sig}`);
+```
+
+The `register_namespace` instruction enforces:
+
+| Constraint | Limit | Error on violation |
+|---|---|---|
+| `name.len() >= 3` | min 3 | `NameTooShort` |
+| `name.len() <= 32` | max 32 | `NameTooLong` |
+| `':'` not in `name` | forbidden | `NamespaceColonForbidden` (so namespace strings pack into URIs without escaping) |
+| `version.len() <= 16` | max 16 | `VersionTooLong` |
+| `schema_uri.len() <= 160` | max 160 | `UriTooLong` |
+
+Anyone can register a namespace — rent (~0.0023 SOL) is the economic deterrent. PolicyVault decides per-policy which attestors it trusts via `accepted_attestors[]`, so a namespace registration alone confers no trust.
+
+## Derive the PDA
+
+```ts
+import { deriveCapabilityNamespacePda } from "@agenttrust-sdk/trustgate";
+
+const namespacePda = deriveCapabilityNamespacePda(
+  DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry,
+  namespaceHash, // 32 bytes
+);
+```
+
+PDA seeds: `["capability", namespace_hash]`.
+
+## Gate a policy against it
+
+Set `required_capability_hash` on `PolicyAccount` when calling `init_policy`:
+
+```ts
+import { BN } from "@coral-xyz/anchor";
+
+await policyVault.methods
+  .initPolicy({
+    policyId:                1,
+    enabledKindsBitmask:     0b11111,  // all five kinds
+    requiredCapabilityHash:  Array.from(namespaceHash),
+    acceptedAttestors:       [/* up to 2 trusted attestor pubkeys, or both PublicKey.default for permissionless */],
+    /* … other policy fields … */
+  })
+  .accounts({
+    /* … */
+  })
+  .rpc();
+```
+
+When PolicyVault's gate runs:
+
+1. If `required_capability_hash == [0; 32]` (zero) — policy is not enabled; pass-through.
+2. Else, look for a `ValidationAttestation` PDA at `["attestation", payee_asset, capability_hash, attestor]`. The `attestor` slot iterates against `accepted_attestors[]`.
+3. If no attestation exists → `RequireValidation(capability_hash)` is returned. The facilitator's `formatChallenge` includes `X-Capability-Required: <hex>` in the x402 response.
+4. After the user obtains an attestation (off-chain claim → attestor calls `respond_to_validation` → PDA written) and re-submits the payment, the gate flips to `Allow`.
+
+Full decision flow: [PolicyVault → RequireValidation policy](/programs/policy-vault/require-validation-policy).
+
+## Naming conventions
+
+The seeded v1 namespaces follow a `domain.subcategory.version` shape:
+
+- `kyc.tier-1.v1`, `kyc.tier-2.v1`, `kyc.tier-3.v1`
+- `audit.smart-contract.v1`, `audit.attestor-firm.v1`
+- `model-card.v1`
+- `jurisdiction.v1`
+- `compliance.payments.v1`
+- `agent-source.v1`
+- `usdc-payment-policy.v1` (the Phase D demo capability)
+
+Full lookup with PDAs and Explorer URLs: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+The playbook-level descriptive labels in [`docs/plan/research/06-validation-registry-class.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/plan/research/06-validation-registry-class.md) (e.g., `kyc.tier-1.v1.identity-verified`) decompose to these on-chain `name` strings plus the JSON `description` field. The chain stores the bounded name; richer metadata lives in the `schema_uri` document.
+
+## Sybil-resistance model — local trust, not global
+
+Permissionless registration plus per-policy `accepted_attestors[]` filtering. PolicyVault decides which attestors it trusts for a given capability, not a central allow-list. A policy that gates against `audit.smart-contract.v1` might only accept attestations from Halborn or OtterSec; a policy that gates against `kyc.tier-1.v1` might accept any registered KYC attestor.
+
+The trade-off is local trust over global gatekeeping — the only model that scales with the number of facilitators. Detailed rationale: [ValidationRegistry](/programs/validation-registry).
+
+## Read next
+
+<Cards>
+  <Card title="Custom attestor" href="/integration-guides/custom-attestor">
+    The other side — register an attestor profile, respond to validation requests, revoke.
+  </Card>
+  <Card title="RequireValidation policy" href="/programs/policy-vault/require-validation-policy">
+    The PolicyVault read path that consumes the attestation PDA.
+  </Card>
+  <Card title="Capability namespaces (live)" href="/reference/capability-namespaces">
+    Every seeded v1 namespace with PDA + Explorer URL.
+  </Card>
+</Cards>

package/dist/embedded-docs/integration-guides/custom-attestor.mdx

@@ -1,15 +1,176 @@
 ---
 title: Custom attestor
-description: How third-party attestors plug into the ValidationRegistry path.
+description: Register an AttestorProfile, respond to validation requests, revoke attestations. Full lifecycle with the live four-signature devnet trace.
 ---
 
-`In progress`
+A custom attestor registers a profile, watches off-chain for validation requests for capabilities it can attest to, signs `respond_to_validation` to write the attestation PDA, and can later revoke any attestation it issued. PolicyVault then reads the resulting PDA at fixed byte offsets.
 
-A custom attestor registers a profile, responds to validation requests, and can revoke an attestation it issued. PolicyVault then reads the resulting PDA by fixed byte offsets.
+Source: [`programs/validation-registry/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/validation-registry). Devnet smoke: [`examples/attestor-demo/`](https://github.com/agenttrust-labs/agenttrust/tree/main/examples/attestor-demo).
 
-| Source | Path |
-| --- | --- |
-| attestor profile | [`programs/validation-registry/src/state/attestor_profile.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/state/attestor_profile.rs) |
-| response instruction | [`programs/validation-registry/src/instructions/respond_to_validation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/respond_to_validation.rs) |
-| revoke instruction | [`programs/validation-registry/src/instructions/revoke_validation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/revoke_validation.rs) |
+## Lifecycle
 
+```
+1. register_attestor   → create AttestorProfile PDA
+2. <off-chain>         → discover ValidationRequest events for capabilities you attest to
+3. respond_to_validation → create ValidationAttestation PDA (PolicyVault now reads it)
+4. revoke_validation   → set revoked = true (PolicyVault now denies)
+```
+
+## Step 1 — register the profile
+
+```ts
+import { Keypair, sendAndConfirmTransaction, Transaction } from "@solana/web3.js";
+import {
+  buildRegisterAttestorIx,
+  loadValidationRegistry,
+  makeProvider,
+  DEFAULT_DEVNET_PROGRAM_IDS,
+} from "@agenttrust-sdk/trustgate";
+
+const attestor = Keypair.fromSecretKey(/* the attestor's signing key */);
+const provider = makeProvider({
+  rpcUrl: "https://api.devnet.solana.com",
+  wallet: attestor,
+});
+
+const validationRegistry = await loadValidationRegistry(
+  provider,
+  DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry,
+);
+
+const ix = await buildRegisterAttestorIx({
+  program:         validationRegistry,
+  attestor:        attestor.publicKey,
+  displayNameUri:  "https://my-org.example/attestor.json",   // ≤ 100 bytes
+});
+
+const tx = new Transaction().add(ix);
+const sig = await sendAndConfirmTransaction(provider.connection, tx, [attestor]);
+```
+
+Constraints: `display_name_uri.len() <= 100` (`UriTooLong` on overflow). Self-registered (the signer is the attestor). PDA: `["attestor", attestor_pubkey]`. Account size includes counters for total attestations + total revoked, all initialised to zero.
+
+## Step 2 — discover validation requests
+
+`request_validation` emits the `RequestCreated` event. Any off-chain process can subscribe:
+
+```ts
+import { PublicKey } from "@solana/web3.js";
+
+provider.connection.onLogs(
+  validationRegistry.programId,
+  (logs) => {
+    if (logs.err) return;
+    // Decode logs.logs entries — RequestCreated event has subject_asset,
+    // capability_hash, requester, claim_uri_hash, deadline.
+  },
+  "confirmed",
+);
+```
+
+For production attestors, [Helius webhooks](https://www.helius.dev/docs/webhooks) on the program's events stream is the standard pattern. The PDA itself is just an audit-trail record; attestors don't read it.
+
+## Step 3 — respond with an attestation
+
+After the attestor verifies the off-chain claim (KYC document, audit report, model-card statement, etc.) the attestor signs `respond_to_validation` to write the on-chain attestation:
+
+```ts
+import {
+  buildRespondToValidationIx,
+  computeCapabilityHash,
+} from "@agenttrust-sdk/trustgate";
+
+const subjectAsset       = new PublicKey("…");                    // payee asset
+const capabilityHash     = computeCapabilityHash("kyc.tier-1.v1"); // 32 bytes
+const claimPayloadHash   = sha256(claim_payload_bytes);            // 32 bytes
+const claimUriHash       = sha256(Buffer.from(claim_uri_string)); // 32 bytes
+const expiresAt          = currentSlot + (30n * 24n * 60n * 60n * 2n);  // ~30 days @ 2 slots/sec
+
+const ix = await buildRespondToValidationIx({
+  program:                validationRegistry,
+  payer:                  attestor.publicKey, // attestor pays rent
+  attestor:               attestor.publicKey,
+  subjectAsset,
+  capabilityHash,
+  claimPayloadHash,
+  claimUriHash,
+  expiresAt: Number(expiresAt),
+});
+
+const sig = await sendAndConfirmTransaction(provider.connection, new Transaction().add(ix), [attestor]);
+```
+
+Constraints: `expires_at == 0` (never expires) OR `expires_at > clock.slot` (`ExpiryInPast` otherwise). The `capability_namespace` PDA must already exist (`AccountNotInitialized` if you reference an unregistered capability). The `attestor_profile` PDA must exist (the attestor must have called `register_attestor` first).
+
+PDA: `["attestation", subject_asset, capability_hash, attestor]`. Account size: 290 bytes.
+
+The v1 trust model is "attestor signs the tx" — the Solana tx signature itself authenticates the attestor. The 64-byte `attestor_signature` field on `ValidationAttestation` is reserved for v1.1+ Ed25519 sysvar verification, which adds non-repudiation against future key compromise.
+
+## Step 4 — revoke when needed
+
+```ts
+import { buildRevokeValidationIx } from "@agenttrust-sdk/trustgate";
+
+const revocationReasonHash = sha256(Buffer.from("kyc-document-expired"));
+
+const ix = await buildRevokeValidationIx({
+  program:               validationRegistry,
+  attestor:              attestor.publicKey,
+  subjectAsset,
+  capabilityHash,
+  revocationReasonHash,
+});
+
+await sendAndConfirmTransaction(provider.connection, new Transaction().add(ix), [attestor]);
+```
+
+`revoke_validation` is audit-trail-preserving: it sets `revoked = true`, writes `revoked_at = clock.slot`, and stores the `revocation_reason_hash`. The PDA is not deleted. PolicyVault's `RequireValidation` policy treats `revoked == true` as `Deny(AttestationRevoked)` (DenyReason code 13).
+
+Only the original attestor can revoke an attestation it issued (`UnauthorizedRevoker` otherwise). v1.1+ adds an external-revoke flow with attestor-profile externals counter.
+
+## Live four-signature trace
+
+End-to-end devnet trace, 2026-05-06 — gate denies → request → respond → gate allows:
+
+| Step | Tx |
+|---|---|
+| `gate_payment` (no attestation) → `RequireValidation` | [`3oKW7QugBLJ7…`](https://explorer.solana.com/tx/3oKW7QugBLJ7kH2QbLLWEuEn3MyNmLWCj3XovCSdDQNmq5HriwNKvPMUR9TQByZPBAPbvprDfdeYDZvh7ofntRRh?cluster=devnet) |
+| `request_validation` | [`2KbXYCF67D2f…`](https://explorer.solana.com/tx/2KbXYCF67D2f2fKHk5yTzrkFBr1mV47Q3Yb1veH5e3PX4PuLa66suodAUc7uTBnr6Y44NGV1TfHHMtAZiFSnbbRF?cluster=devnet) |
+| `respond_to_validation` (creates attestation) | [`67CzMS9GEt…`](https://explorer.solana.com/tx/67CzMS9GEtUBesNznKpT2UWqvjEBzhgZd7AVkhXKQ5SoqRoBotcaYf1sTF8sHxj55TNT9k847nj7FQdrwAqKussp?cluster=devnet) |
+| `gate_payment` (with attestation) → `Allow` | [`dEXkCEeSn8…`](https://explorer.solana.com/tx/dEXkCEeSn8uiVAa14u7EusdFufSuUQttmcTdLHMSq5J3VSARM4KMRCfwpRSkVmYBc1yRQuyvPMCebifCf1dmrmC?cluster=devnet) |
+
+Resulting `ValidationAttestation` PDA: [`8YKq…xt2q`](https://explorer.solana.com/address/8YKqxoBaKfQ4VcDNa6dcoMQGevxbRmcr4ENbWcyrJxt2q?cluster=devnet). Reproduce with `pnpm --filter ./examples/attestor-demo run chained` (~0.012 SOL total). Full trace: [Verification → Chained validation](/verification/chained-validation).
+
+## How the gate consumes your attestation
+
+PolicyVault's `RequireValidation` policy reads the `ValidationAttestation` at fixed byte offsets:
+
+| Offset | Width | Field |
+|---:|---:|---|
+| `8` | Pubkey | `subject_asset` |
+| `40` | [u8; 32] | `capability_hash` |
+| `72` | Pubkey | `attestor` |
+| `208` | u64 LE | `expires_at` (0 = never expires) |
+| `216` | bool | `revoked` |
+
+A policy with `accepted_attestors = [your_pubkey, …]` accepts attestations only from your key. Permissionless mode (both `accepted_attestors` slots zero) accepts any attestor's signature for the capability. Full read semantics: [RequireValidation policy](/programs/policy-vault/require-validation-policy).
+
+## Validation against the Kani proof
+
+The `validation_expiry_correct` proof (Kani #4, 85 sub-checks, 0.23 s) pins: an expired attestation cannot produce `Allow` from `require_validation::evaluate`. Even if all other fields match, expiry is the deciding gate.
+
+So if you set `expires_at = currentSlot + 1000` and waited 1000 slots, your attestation goes from `Allow`-capable to `Deny(AttestationExpired)` automatically — no revocation tx required. Plan attestation lifetimes accordingly. Reference: [Verification → Kani proofs](/verification/kani-proofs).
+
+## Read next
+
+<Cards>
+  <Card title="Capability namespaces" href="/integration-guides/capability-namespaces">
+    Register the capability your attestation references.
+  </Card>
+  <Card title="ValidationRegistry" href="/programs/validation-registry">
+    All five instructions, all four PDAs, byte-precise.
+  </Card>
+  <Card title="Chained validation" href="/verification/chained-validation">
+    The full live four-signature trace with reproduction commands.
+  </Card>
+</Cards>

package/dist/embedded-docs/integration-guides/dexter-adapter.mdx

@@ -0,0 +1,76 @@
+---
+title: Dexter adapter
+description: In-flight worked example — the second AgentTrust facilitator adapter, used to prove portability of the FacilitatorAdapter contract.
+---
+
+Dexter is the second facilitator AgentTrust supports. It exists to prove that the `FacilitatorAdapter` contract is portable: every adapter must implement the same five methods, expose the same Zod-validated wire schemas, and use the same SDK factories for on-chain validation and feedback emission. If wiring a second adapter forces route edits, policy edits, or registry-read changes, the adapter boundary failed and gets fixed before the integration ships.
+
+Status: in flight. The current repo carries a stub at [`trustgate/server/src/facilitators/dexter/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/dexter) that satisfies the type contract; full implementation lands once Dexter publishes its x402 wire format. Current adapter status: [`agenttrust_list_facilitators`](/mcp/tools#agenttrust_list_facilitators) → `{ name: "dexter", status: "in-flight" }`.
+
+## What the adapter has to land
+
+The five methods every adapter implements, with Dexter-specific notes:
+
+| Method | Dexter-specific note |
+|---|---|
+| `parseRequest(req)` | Translate Dexter's body shape + headers (TBD until spec lands) into `VerifyContext`. Strict Zod schema — reject unknown root fields. |
+| `formatChallenge(decision, ctx)` | Render `Allow` / `Deny` / `RequireValidation` in Dexter's response shape. Headers: `X-Agent-Trust-Decision`, `X-Capability-Required` (when applicable). |
+| `formatSettlement(ctx)` | Return Dexter's settlement metadata or an unsigned transaction skeleton. Payment ID and amount/mint/recipient are bound to the verify-time context. |
+| `validatePaymentProof(proof, ctx)` | Verify the proof shape; cross-check against `VerifyContext`. Same defenses as Pay.sh: replay, self-pay, amount, mint, recipient, expiry. |
+| `emitFeedback(ctx, settlement)` | Call the feedback CPI idempotently via `priorEmissionLookup` + `emitFeedbackCpi`. |
+
+Implementation pattern: read [`facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh) end to end. Adapt the schemas + signature semantics to Dexter's wire format. Keep the proof-validator's defense list 1:1.
+
+## Why Dexter exists in the catalog
+
+Pay.sh proves the adapter pattern handles the canonical x402 case. Dexter exists to prove the pattern handles a *different* x402 facilitator's quirks without forcing route layer changes. The same `FacilitatorRegistry` registers it; the same `/verify`, `/settle`, `/dispute` routes dispatch to it; the same SDK factories build its on-chain calls.
+
+```ts
+import { FacilitatorRegistry, PaySh } from "./facilitators";
+import { Dexter } from "./facilitators/dexter";
+
+const registry = new FacilitatorRegistry();
+registry.register(new PaySh(payShDeps));
+registry.register(new Dexter(dexterDeps));
+registry.setDefault("pay-sh");
+```
+
+The route layer never branches on the facilitator name — selection happens via the `X-Facilitator` request header or the registry's default. Dexter requests use `X-Facilitator: dexter`; everything else routes to Pay.sh.
+
+## What lands when Dexter ships
+
+| Deliverable | Where |
+|---|---|
+| `Dexter` class | `trustgate/server/src/facilitators/dexter/index.ts` |
+| Zod schemas | `trustgate/server/src/facilitators/dexter/schemas.ts` |
+| Proof validator | `trustgate/server/src/facilitators/dexter/proof-validator.ts` |
+| Feedback helper | `trustgate/server/src/facilitators/dexter/feedback.ts` |
+| Demo (optional) | `examples/dexter-demo/` |
+| Adapter test suite | `trustgate/server/test/facilitators/dexter/` |
+
+Each file mirrors the Pay.sh shape. The adapter test suite asserts the `FacilitatorAdapter` contract conformance — every method's input is type-safe and every method's output matches the documented schema.
+
+## Adapter contract conformance
+
+CI runs an adapter-contract conformance workflow ([`.github/workflows/adapter-contract-conformance.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/adapter-contract-conformance.yml)) on every PR. It walks every registered adapter and asserts:
+
+- `parseRequest` accepts the verify-shape and rejects malformed inputs with `400`.
+- `formatChallenge` emits the right headers per decision arm.
+- `validatePaymentProof` rejects every member of the standard hostile-input matrix (replay, self-pay, mismatch, expired).
+- `emitFeedback` is idempotent against the same `payment_id_hash`.
+
+Dexter (when shipped) and any future adapter (atxp, MCPay) hook into the same conformance check. The Pay.sh adapter is the conformance reference — its 50+ test cases cover every branch of the contract.
+
+## Read next
+
+<Cards>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    The canonical implementation. Read it end to end before writing your own.
+  </Card>
+  <Card title="Facilitator adapters" href="/integration-guides/facilitator-adapters">
+    The five-method contract in full.
+  </Card>
+  <Card title="Custom attestor" href="/integration-guides/custom-attestor">
+    If you're attesting capabilities rather than running a facilitator.
+  </Card>
+</Cards>

package/dist/embedded-docs/integration-guides/facilitator-adapters.mdx

@@ -1,85 +1,129 @@
 ---
 title: Facilitator adapters
-description: Add a new x402 facilitator without rewriting AgentTrust routes or policy.
+description: Add a new x402 facilitator without rewriting AgentTrust routes or policy. Five-method contract, registry-based dispatch, conformance-tested.
 ---
 
-The adapter layer is the reason AgentTrust is not locked to Pay.sh. Pay.sh is live today; Dexter is the next worked path; atxp_ai and MCPay are marked roadmap through explicit stubs.
+The adapter layer is what makes AgentTrust facilitator-agnostic. Pay.sh is the canonical reference; Dexter is the in-flight second worked example; atxp and MCPay are roadmap. Routes (`/verify`, `/settle`, `/dispute`), the PolicyVault gate, and the registry reads do not branch on facilitator name. Protocol quirks live in one adapter file.
+
+The adapter implementations live in [`trustgate/server/src/facilitators/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators). The server package is workspace-internal (not published to npm); copy the pattern from [`facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh) into your own server, or use the published [SDK middleware](/sdk/mount-trustgate) which dispatches through the adapter layer for you.
 
 ## Mental model
 
-```txt
+```
 HTTP request
-  -> routes/{verify,settle}
-  -> FacilitatorRegistry
-  -> active FacilitatorAdapter
-  -> VerifyContext
-  -> policy decision
-  -> settlement proof validation
-  -> feedback emission
+   → /verify · /settle · /dispute
+   → FacilitatorRegistry  (selects adapter by X-Facilitator header or default)
+   → active FacilitatorAdapter
+   → VerifyContext
+   → PolicyVault gate decision
+   → settlement proof validation
+   → feedback emission
 ```
 
-Routes, policy logic, and registry reads stay unchanged. Protocol quirks live in one adapter file.
+The active adapter is the only code that knows about the chosen facilitator.
 
 ## The five-method contract
 
+```ts
+export interface FacilitatorAdapter {
+  readonly protocol: FacilitatorProtocol; // identity tag for registry
+
+  parseRequest(req: Request): Promise<VerifyContext>;
+  formatChallenge(decision: GateDecision, ctx: VerifyContext): ChallengeResponse;
+  formatSettlement(ctx: VerifyContext): SettlementResponse;
+  validatePaymentProof(proof: unknown, ctx: VerifyContext): Promise<PaymentProofValidation>;
+  emitFeedback(ctx: VerifyContext, settlement: ConfirmedSettlement): Promise<FeedbackEmissionResult>;
+}
+```
+
 | Method | Why it exists |
-| --- | --- |
-| `parseRequest(req)` | translate the facilitator's request body and headers into `VerifyContext` |
-| `formatChallenge(decision, ctx)` | render Allow / Deny / RequireValidation in that facilitator's wire format |
-| `formatSettlement(ctx)` | return protocol-specific settlement metadata or an unsigned transaction skeleton |
-| `validatePaymentProof(proof, ctx)` | verify proof shape and cross-check it against the verify-time context |
-| `emitFeedback(ctx, settlement)` | emit the AgentTrust feedback record after settlement |
+|---|---|
+| `parseRequest(req)` | Translate the facilitator's request body and headers into `VerifyContext` |
+| `formatChallenge(decision, ctx)` | Render `Allow` / `Deny` / `RequireValidation` in that facilitator's wire format |
+| `formatSettlement(ctx)` | Return protocol-specific settlement metadata or an unsigned transaction skeleton |
+| `validatePaymentProof(proof, ctx)` | Verify proof shape and cross-check against the verify-time context |
+| `emitFeedback(ctx, settlement)` | Emit the AgentTrust feedback record idempotently |
 
 If an adapter needs a sixth method, that is a contract change, not a one-off escape hatch.
 
 ## Status map
 
 | Facilitator | Repo status | Meaning |
-| --- | --- | --- |
-| Pay.sh | concrete adapter | ready path for the demo and production dependency factory |
-| Dexter | stub / in flight | worked example for proving adapter portability |
-| atxp_ai | stub | roadmap, not silently unsupported |
-| MCPay | stub | roadmap, not silently unsupported |
+|---|---|---|
+| Pay.sh | concrete adapter | Ready for the demo + production dependency factory; the canonical `FacilitatorAdapter` reference |
+| Dexter | in-flight stub | Worked example for proving adapter portability |
+| atxp | roadmap stub | Tracked, not silently unsupported |
+| MCPay | roadmap stub | Tracked, not silently unsupported |
+
+`agenttrust_list_facilitators` (an MCP tool) returns the live status set: [MCP → Tools](/mcp/tools#agenttrust_list_facilitators).
 
 ## Add a facilitator
 
-1. Read the facilitator's wire format. Identify challenge headers, proof headers, body shape, recipient encoding, payment ID hints, and Allow / Deny responses.
-2. Define strict Zod schemas for the request body and proof payload.
+1. Read the facilitator's wire format. Identify challenge headers, proof headers, body shape, recipient encoding, payment ID hints, Allow/Deny responses.
+2. Define strict Zod schemas for the request body and proof payload. Reject unknown root fields.
 3. Implement one `FacilitatorAdapter` class.
-4. Re-export it from `trustgate/server/src/facilitators/index.ts`.
-5. Register it with `FacilitatorRegistry`.
-6. Add unit tests that mirror Pay.sh coverage.
+4. Re-export from [`trustgate/server/src/facilitators/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/index.ts).
+5. Register with `FacilitatorRegistry`.
+6. Add unit tests mirroring Pay.sh coverage (50+ cases — schema, signature, proof-validator, feedback idempotency).
 7. Add a demo under `examples/<name>-demo` if the integration needs a runnable walkthrough.
 
 ## Registry wiring
 
 ```ts
-import {
-  FacilitatorRegistry,
-  PaySh,
-} from "@agenttrust/trustgate-server";
+import { FacilitatorRegistry, PaySh } from "./facilitators";
+import { Dexter } from "./facilitators/dexter";
 
 const registry = new FacilitatorRegistry();
 registry.register(new PaySh(payShDeps));
+registry.register(new Dexter(dexterDeps));
 registry.setDefault("pay-sh");
+
+// Per-request selection via X-Facilitator header:
+//   curl -H "X-Facilitator: dexter" …
+// Falls back to default if header is absent.
 ```
 
-Request-time selection can come from `X-Facilitator`, environment defaults, or a programmatic default. The active adapter is the only code that knows about the chosen facilitator.
+The registry resolves the active adapter on every `/verify`, `/settle`, `/dispute` call. The dispatch site is one line; nothing in the route layer knows which adapter is active.
 
 ## Security checklist
 
 Every adapter must preserve the same proof-of-payment checks:
 
-- replay defense
-- self-pay defense
-- amount, mint, and recipient cross-checks
-- network match
-- expiry window
-- idempotent feedback emission
-- stable reason codes on Deny
+- replay defense — reject proofs whose `paymentIdHash` matches a prior settlement
+- self-pay defense — reject proofs where transfer authority equals facilitator fee payer
+- amount, mint, recipient cross-checks — reject if the proof references different values than the verify-time context
+- network match — reject mainnet proofs against a devnet-bound facilitator
+- expiry window — reject proofs older than the SERVICE-signed challenge's `issuedAt + maxTimeoutSeconds`
+- idempotent feedback emission — `priorEmissionLookup` short-circuits a second emission for the same `payment_id_hash`
+- stable reason codes on `Deny` — clients consume the numeric `reasonCode`, decoupled from Borsh wire-format ordering
+
+The Pay.sh adapter's [`proof-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/proof-validator.ts) and [`feedback.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/feedback.ts) are the reference pattern.
+
+## Conformance test
+
+CI runs [`.github/workflows/adapter-contract-conformance.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/adapter-contract-conformance.yml) on every PR. The workflow walks every registered adapter and asserts:
+
+- `parseRequest` accepts the verify-shape and rejects malformed inputs with HTTP `400`.
+- `formatChallenge` emits the right headers per decision arm (Allow, Deny + reason, RequireValidation + capability hash).
+- `validatePaymentProof` rejects every entry in the hostile-input matrix.
+- `emitFeedback` is idempotent — a second call for the same `payment_id_hash` returns the prior emission's signature instead of double-emitting.
 
-Pay.sh's `proof-validator.ts` and `feedback.ts` are the reference pattern.
+Adversarial-harness coverage: [Verification → Adversarial harness](/verification/adversarial-harness).
 
 ## Target integration time
 
-The architecture target is under two hours for a facilitator that already has a clear x402 wire spec. If adding a facilitator forces route edits, policy edits, or registry read changes, the adapter boundary failed and should be fixed before the integration is considered done.
+The architecture target is **under two hours** for a facilitator that already has a clear x402 wire spec. If adding a facilitator forces route edits, policy edits, or registry-read changes, the adapter boundary failed and gets fixed before the integration is considered done.
+
+## Read next
+
+<Cards>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    Walk through the canonical implementation end to end.
+  </Card>
+  <Card title="Dexter adapter" href="/integration-guides/dexter-adapter">
+    See how the second adapter slots into the same contract.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Why every adapter's settle path keeps gate + transfer + feedback in one tx.
+  </Card>
+</Cards>