@agenttrust-sdk/mcp 0.2.5 → 0.3.0

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>

package/dist/embedded-docs/integration-guides/pay-sh-adapter.mdx

@@ -1,33 +1,52 @@
 ---
 title: Pay.sh adapter
-description: The live Pay.sh + AgentTrust integration path.
+description: Walk the live Pay.sh + AgentTrust integration end to end — challenge, retry, settle, feedback, with hosted-demo paths and the SERVICE-signed envelope contract.
 ---
 
-Pay.sh is the first concrete AgentTrust facilitator adapter. It translates Pay.sh's x402 headers and `PaymentRequirements` body into the `VerifyContext` that the on-chain policy path understands.
-
-Pay.sh launch reference: [Solana Foundation launch note](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud).
+Pay.sh is the Solana Foundation's first x402 facilitator, [launched 2026-05-05 with Google Cloud](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud). AgentTrust ships day-one Pay.sh integration as the canonical `FacilitatorAdapter` implementation. Source: [`trustgate/server/src/facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh).
 
 ## What the adapter does
 
-| Stage | Pay.sh / x402 surface | AgentTrust action |
-| --- | --- | --- |
+| Stage | x402 / Pay.sh wire shape | AgentTrust action |
+|---|---|---|
 | Initial request | no payment proof | emit `402 Payment Required` with a base64 x402 v2 envelope |
-| Challenge | `paymentRequirements.extra.agentTrust` | include payer agent, payee agent, payee recipient, policy ID, `issuedAt`, and `serviceSignature` |
-| Retry | `PAYMENT-SIGNATURE` or `X-PAYMENT` | parse proof and rebuild `VerifyContext` |
-| Policy | `VerifyContext` | run the gate decision |
+| Challenge | `paymentRequirements.extra.agentTrust` | include payer agent, payee agent, payee recipient, policy ID, `issuedAt`, `serviceSignature` |
+| Retry | `PAYMENT-SIGNATURE` or `X-PAYMENT` header | parse proof, rebuild `VerifyContext` |
+| Policy | `VerifyContext` | run `gate_payment` decision |
 | Allow | signed payment proof | validate transfer fields, emit feedback, forward resource |
-| Deny | gate decision | return `402` with reason code and reason name |
+| Deny | gate decision | return `402` with reason code + reason name |
 
-## Files to read
+## Hit the live demo
 
-| File | Purpose |
-| --- | --- |
-| `trustgate/server/src/facilitators/pay-sh/index.ts` | the five-method `PaySh` class |
-| `trustgate/server/src/facilitators/pay-sh/schemas.ts` | strict Zod wire schemas |
-| `trustgate/server/src/facilitators/pay-sh/sig.ts` | SERVICE challenge signature helpers |
-| `trustgate/server/src/facilitators/pay-sh/proof-validator.ts` | replay, self-pay, amount, mint, recipient checks |
-| `trustgate/server/src/facilitators/pay-sh/feedback.ts` | idempotent feedback emission |
-| `examples/pay-sh-demo/src/middleware.ts` | Express route bridge from Pay.sh retry to AgentTrust |
+[`demo.agenttrust.tech`](https://demo.agenttrust.tech) runs the full Pay.sh + AgentTrust pipeline against deployed devnet programs. With no payment proof:
+
+```bash
+curl -i https://demo.agenttrust.tech/protected
+```
+
+Returns `HTTP/2 402` with a SERVICE-signed `payment-required` envelope. With Pay.sh installed, let the CLI pay and retry:
+
+```bash
+pay --sandbox curl https://demo.agenttrust.tech/protected
+```
+
+The demo seeds three deterministic counterparties. Drive each branch by passing the matching `X-Demo-Payer-Agent` header:
+
+```bash
+# Allow path (tier 3)
+PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[2].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
+
+# Deny path (tier 0)
+PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[0].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
+```
+
+| Counterparty tier | Decision |
+|---:|---|
+| 0 | `402 Deny — CounterpartyTierBelowMin` |
+| 1 | `402 Deny — CounterpartyTierBelowMin` |
+| 3 | `200 Allow + X-Payment-Receipt` |
 
 ## SERVICE-signed challenge
 
@@ -44,58 +63,49 @@ The SERVICE emits a signed challenge when it returns the Pay.sh `402` response.
 - policy ID
 - payment ID hash
 
-`PaySh.parseRequest()` verifies that signature against the facilitator public key before it accepts the request. This closes the race window where a forged `paymentRequirements` envelope could be raced against the legitimate one.
-
-## Run the demo
+`PaySh.parseRequest()` verifies that signature against the facilitator public key before accepting the request. This closes the race window where a forged `paymentRequirements` envelope could race a legitimate one.
 
-```bash
-pnpm --filter ./examples/pay-sh-demo dev
-```
+## Files to read in repo
 
-```bash
-pay --sandbox curl https://demo.agenttrust.tech/protected
-```
-
-The demo uses three deterministic counterparties:
-
-| Counterparty tier | Expected result |
-| --- | --- |
-| 0 | `402 Deny` with `CounterpartyTierBelowMin` |
-| 1 | `402 Deny` with `CounterpartyTierBelowMin` |
-| 3 | `200 Allow` with `X-Payment-Receipt` |
-
-Get the exact payer agent keys:
-
-```bash
-curl -s https://demo.agenttrust.tech/health | jq '.counterparties'
-```
+| File | Purpose |
+|---|---|
+| [`facilitators/pay-sh/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/index.ts) | The five-method `PaySh` class |
+| [`facilitators/pay-sh/schemas.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/schemas.ts) | Strict Zod wire schemas |
+| [`facilitators/pay-sh/sig.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/sig.ts) | SERVICE challenge signature helpers |
+| [`facilitators/pay-sh/proof-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/proof-validator.ts) | Replay, self-pay, amount, mint, recipient checks |
+| [`facilitators/pay-sh/feedback.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/feedback.ts) | Idempotent feedback emission |
+| [`examples/pay-sh-demo/src/middleware.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/pay-sh-demo/src/middleware.ts) | Express bridge from Pay.sh retry to AgentTrust |
 
 ## Production wiring
 
-The demo proves the pipeline without requiring devnet RPC in CI. The server package carries the real devnet Anchor route: `trustgate/server/src/chain.ts` loads deployed program IDLs, `/verify` simulates `gate_payment`, and `/settle` delegates proof validation plus feedback emission through the active adapter.
+The demo proves the pipeline without requiring devnet RPC in CI. The server package carries the real devnet path: [`trustgate/server/src/chain.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/chain.ts) loads deployed program IDLs, `/verify` simulates `gate_payment`, and `/settle` delegates proof validation plus feedback emission through the active adapter.
 
-Production swaps three dependency seams:
+Production swaps three dependency seams the demo stubs:
 
 ```ts
+import { PaySh } from "./facilitators/pay-sh";
+
 const adapter = new PaySh({
   signingNetwork: "solana-devnet",
-  feePayer: facilitator.publicKey,
-  validateOnChainTx,
-  emitFeedbackCpi,
-  priorEmissionLookup,
-  replayCache,
-  signDecision,
+  feePayer:       facilitator.publicKey,
+  validateOnChainTx,        // makeValidateOnChainTx({ connection, … })
+  emitFeedbackCpi,          // makeEmitFeedbackCpi({ connection, programIds, … })
+  priorEmissionLookup,      // makePriorEmissionLookup({ connection, programId })
+  replayCache,              // ReplayCache (in-memory by default)
+  signDecision,             // signs canonical decision bytes with facilitator key
 });
 ```
 
 | Dependency | Production implementation |
-| --- | --- |
+|---|---|
 | `validateOnChainTx` | parse the confirmed SPL transfer transaction from RPC |
 | `emitFeedbackCpi` | build and send `trustgate::emit_feedback` through Anchor |
 | `priorEmissionLookup` | read the `FeedbackEmissionLog` PDA by payment hash |
 | `signDecision` | sign canonical decision bytes with the facilitator key |
 
-## Failure cases to keep
+The factories (`makeValidateOnChainTx`, `makeEmitFeedbackCpi`, `makePriorEmissionLookup`) are SDK exports — see [SDK → Exports reference](/sdk/exports-reference).
+
+## Failure cases the adapter must keep
 
 Do not remove these checks when adapting Pay.sh into a production server:
 
@@ -105,6 +115,32 @@ Do not remove these checks when adapting Pay.sh into a production server:
 - reject `payTo` / `payeeRecipient` mismatch
 - reject expired challenges
 - reject replayed proof bindings
-- reject transfer authority equal to facilitator fee payer
+- reject transfer authority equal to facilitator fee payer (self-pay defense)
+
+These are part of the adapter, not the route layer. 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) is the reference implementation.
+
+## Live evidence
+
+Real atomic-settlement trace on devnet (2026-05-06):
+
+| Step | Tx |
+|---|---|
+| Signed SPL `transferChecked` | [`5iV8EYmJh9XS…`](https://explorer.solana.com/tx/5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD?cluster=devnet) |
+| `emit_feedback` PDA-signed CPI | [`jMobmWJUAXuL8…`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) |
+| `FeedbackEmissionLog` PDA | [`HB4BBi9j…`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) |
+
+Full trace + reproduction commands: [Verification → Devnet smoke](/verification/devnet-smoke).
+
+## Read next
 
-These checks are part of the adapter, not the route layer.
+<Cards>
+  <Card title="Facilitator adapters" href="/integration-guides/facilitator-adapters">
+    The five-method contract every adapter satisfies. Build your own.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Why the gate, transfer, and feedback must execute as one Solana tx.
+  </Card>
+  <Card title="mountTrustGate" href="/sdk/mount-trustgate">
+    The SDK middleware that backs the adapter dispatch.
+  </Card>
+</Cards>