@agenttrust-sdk/mcp 0.2.6 → 0.3.0

package/dist/embedded-docs/programs/trustgate.mdx

@@ -1,53 +1,135 @@
 ---
 title: TrustGate
-description: The x402 facilitator program that emits ERC-8004 feedback through Quantu.
+description: The facilitator-side Anchor program — PDA-signed feedback CPIs into Quantu and per-payment idempotency receipts.
 ---
 
-TrustGate is the on-chain feedback bridge for x402 facilitators. It owns a per-facilitator PDA, signs feedback CPI calls into Quantu, and records idempotency by payment hash.
+TrustGate is the program a facilitator owns. One PDA per facilitator (`TrustGateAuthority`) signs CPIs into Quantu's `agent-registry-8004::give_feedback`. One PDA per payment (`FeedbackEmissionLog`) is the on-chain idempotency receipt. Three instructions.
 
-Pay.sh uses this path through the `PaySh` adapter. Other facilitators should reach the same on-chain instruction through their own adapter rather than adding facilitator-specific branches to routes.
+**Devnet:** [`HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N`](https://explorer.solana.com/address/HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N?cluster=devnet)
 
 ## Instructions
 
-| Instruction | Purpose |
-| --- | --- |
-| `init_authority(facilitator)` | creates the facilitator PDA |
-| `emit_feedback(...)` | CPI into Quantu `agent_registry_8004::give_feedback` |
-| `dispute_payment(...)` | emits negative-score feedback for disputed payments |
+| Instruction | Effect |
+|---|---|
+| `init_authority(facilitator)` | Create `TrustGateAuthority` PDA for `facilitator`. One-time per facilitator. |
+| `emit_feedback(payment_id_hash, facilitator, payee_asset, score, tag1, tag2, endpoint, feedback_uri)` | PDA-signed CPI into `agent-registry-8004::give_feedback`. Initialises `FeedbackEmissionLog`. |
+| `dispute_payment(payment_id_hash, facilitator, payee_asset, dispute_reason_hash, feedback_uri)` | PDA-signed CPI emitting NEGATIVE-score feedback (score = `DISPUTE_SCORE`, tag1 = `dispute`). Initialises `FeedbackEmissionLog`. |
+
+Both `emit_feedback` and `dispute_payment` enforce `signer == facilitator` (`FacilitatorSignerMismatch`). Without that guard, anyone could write fake feedback under any facilitator's authority — a real attack against on-chain reputation.
+
+## State accounts
+
+### `TrustGateAuthority`
+
+```rust
+#[account]
+pub struct TrustGateAuthority {
+    pub facilitator: Pubkey,  // off  8..40 — external facilitator wallet
+    pub bump: u8,             // off 40
+    pub _pad0: [u8; 7],       // off 41..48
+    pub feedback_count: u64,  // off 48..56 — total successful give_feedback CPIs
+    pub dispute_count: u64,   // off 56..64 — total dispute_payment CPIs
+    pub created_at_slot: u64, // off 64..72
+    pub _reserved: [u8; 32],  // off 72..104
+}
+```
 
-## PDA signer
+PDA seeds: `["trustgate_auth", facilitator]`. Different facilitators (Pay.sh, Dexter, atxp, MCPay) each get their own PDA, so feedback emission is namespaced per-facilitator on-chain. The `feedback_count` and `dispute_count` accumulate as that facilitator emits.
+
+### `FeedbackEmissionLog`
+
+```rust
+#[account]
+pub struct FeedbackEmissionLog {
+    pub payment_id_hash: [u8; 32], // off  8..40 — caller-supplied payment ID hash
+    pub bump: u8,                  // off 40
+    pub score: u8,                 // off 41 — score that was emitted
+    pub is_dispute: u8,            // off 42 — 1 = dispute path, 0 = emit_feedback path
+    pub _pad0: [u8; 5],            // off 43..48
+    pub emitted_at_slot: u64,      // off 48..56
+    pub _reserved: [u8; 16],       // off 56..72
+}
+```
 
-TrustGate signs CPI with:
+PDA seeds: `["feedback_log", payment_id_hash]`. The init-only constraint is the idempotency mechanism: a second `emit_feedback` (or `dispute_payment`) for the same `payment_id_hash` fails with `account-already-in-use` and the entire transaction reverts. There is no recovery path — that is exactly the desired property: a successful CPI mints exactly one feedback per payment.
 
-```txt
-["trustgate_auth", facilitator_pubkey, bump]
-```
+The caller computes `payment_id_hash = SHA-256(payment_id_string)` off-chain. The SDK does this in [`composeAtomicSettleTx`](/sdk/mount-trustgate); facilitators that build their own settlement path replicate the same hash construction.
 
-That PDA is the feedback authority, not the payee agent. This prevents self-feedback while allowing a facilitator to write receipt-grade feedback after settlement.
+## PDA-signed CPI to Quantu
 
-## Feedback idempotency
+`emit_feedback` PDA-signs the CPI into Quantu's `agent-registry-8004::give_feedback`:
 
-`FeedbackEmissionLog` is initialized at:
+```rust
+let signer_seeds: &[&[u8]] = &[
+    TrustGateAuthority::SEED_PREFIX,    // b"trustgate_auth"
+    facilitator.as_ref(),
+    &[bump],
+];
+invoke_give_feedback(&cpi_accounts, &args, signer_seeds)?;
+```
 
-```txt
-["feedback_log", payment_id_hash]
+Quantu's `give_feedback` instruction expects the caller to be the agent's owner — TrustGate's PDA is registered as the feedback authority via Quantu's identity flow on first use. The `client` account in the CPI is set to `authority.to_account_info()`, so Quantu sees a PDA-signed call rather than the facilitator's wallet directly.
+
+`remaining_accounts` ordering for the CPI:
+
+| Index | Account | Notes |
+|---:|---|---|
+| 0 | `agent_account` | payee's Quantu `AgentAccount` PDA |
+| 1 | `asset` | payee's Metaplex Core asset |
+| 2 | `collection` | Quantu's collection asset |
+| 3 | `system_program` | for rent on AtomStats init |
+| 4 | `atom_config` (optional) | Quantu's `AtomConfig` PDA |
+| 5 | `atom_stats` (optional) | payee's `AtomStats` PDA — created on first feedback |
+| 6 | `atom_engine_program` (optional) | Quantu's atom-engine program |
+| 7 | `registry_authority` (optional) | Quantu's registry authority PDA |
+
+Indexes 0..=3 are required (`AgentRegistryProgramMismatch` on count mismatch). Indexes 4..=7 come as a group of 4 — pass all four or none. The SDK's `composeAtomicSettleTx` builds this account list correctly; integrators going lower-level should consult [`programs/trustgate/src/ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs).
+
+## `give_feedback` args
+
+```rust
+pub struct GiveFeedbackArgs {
+    pub value: u64,
+    pub value_decimals: u8,
+    pub score: Option<u8>,                      // 0..=100
+    pub feedback_file_hash: Option<[u8; 32]>,   // dispute_reason_hash for disputes
+    pub tag1: String,                           // ≤ 32 bytes
+    pub tag2: String,                           // ≤ 32 bytes
+    pub endpoint: String,                       // ≤ 64 bytes
+    pub feedback_uri: String,                   // ≤ 256 bytes
+}
 ```
 
-Reusing the same payment hash fails account initialization, so retries cannot double-emit feedback.
+`emit_feedback` validates `score ≤ 100`, `tag1.len() ≤ 32`, `tag2.len() ≤ 32`, `endpoint.len() ≤ 64`, `feedback_uri.len() ≤ 256`. Discriminator: `[145, 136, 123, 3, 215, 165, 98, 41]` ([Reference → Discriminator constants](/reference/discriminator-constants)).
+
+## Disputes
+
+`dispute_payment` is the negative-feedback path. Per `docs/plan/research/04-policyvault-build-playbook.md §C.4`, revocations are events-only; new negative feedback is the canonical "downstream consumers see and react to" signal. The handler:
+
+- Requires `dispute_reason_hash != [0; 32]` (`DisputeReasonRequired`).
+- Hard-codes `score = DISPUTE_SCORE`, `tag1 = "dispute"`.
+- Sets `tag2` to the first 16 hex chars of the dispute reason hash for off-chain consumers.
+- Sets `is_dispute = 1` on the `FeedbackEmissionLog`.
+
+Same idempotency pattern: the `init` constraint blocks double-disputes per `payment_id_hash`.
+
+## Events
 
-## x402 mapping
+| Event | Fields |
+|---|---|
+| `AuthorityInitialized` | `facilitator`, `authority`, `slot` |
+| `FeedbackEmitted` | `facilitator`, `payee_asset`, `payment_id_hash`, `score`, `slot` |
+| `PaymentDisputed` | `facilitator`, `payee_asset`, `payment_id_hash`, `dispute_reason_hash`, `slot` |
 
-The SDK and server map PolicyVault outcomes into response headers:
+## Live trace
 
-| Decision | HTTP | Headers |
-| --- | --- | --- |
-| `Allow` | `200` | `X-Agent-Trust-Decision: Allow` |
-| `Deny` | `402` | reason code and reason name |
-| `RequireValidation` | `402` | required capability hash |
+Real `emit_feedback` CPI on devnet, captured 2026-05-06: [`jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) — the resulting `FeedbackEmissionLog` PDA at [`HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) has `score=100`, `is_dispute=0`. Full trace: [Verification → Devnet smoke](/verification/devnet-smoke).
 
 ## Source
 
-- Program: `programs/trustgate/src/lib.rs`
-- CPI wrapper: `programs/trustgate/src/ext/agent_registry.rs`
-- Server route layer: `trustgate/server/src/routes/verify.ts`
-- Pay.sh adapter: `trustgate/server/src/facilitators/pay-sh/index.ts`
+- Program entry: [`programs/trustgate/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/lib.rs)
+- `emit_feedback`: [`instructions/emit_feedback.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/instructions/emit_feedback.rs)
+- `dispute_payment`: [`instructions/dispute_payment.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/instructions/dispute_payment.rs)
+- `init_authority`: [`instructions/init_authority.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/instructions/init_authority.rs)
+- CPI wrapper: [`ext/agent_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/trustgate/src/ext/agent_registry.rs)
+- State: [`state/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/trustgate/src/state)

package/dist/embedded-docs/programs/validation-registry.mdx

@@ -1,49 +1,156 @@
 ---
 title: ValidationRegistry
-description: Capability namespaces, attestors, requests, responses, and revocations.
+description: Capability namespaces, attestor profiles, validation requests, and attestation PDAs — the third leg of ERC-8004 on Solana.
 ---
 
-ValidationRegistry is the attestation leg of AgentTrust. PolicyVault reads `ValidationAttestation` accounts when `RequireValidation` is enabled.
+ValidationRegistry productizes the ERC-8004 V variant on Solana. Permissionless namespace + attestor registration; downstream-consumer filtering in PolicyVault. Five instructions over four PDAs.
 
-## Accounts
-
-| PDA | Role |
-| --- | --- |
-| `CapabilityNamespace` | names a validation capability and schema URI |
-| `AttestorProfile` | records an attestor identity URI |
-| `ValidationRequest` | opens a request for an agent and capability |
-| `ValidationAttestation` | stores a response, expiry, and revoked flag |
+**Devnet:** [`Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`](https://explorer.solana.com/address/Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv?cluster=devnet)
 
 ## Instructions
 
-| Instruction | Notes |
-| --- | --- |
-| `register_namespace` | permissionless, caller computes `SHA256(name_utf8)` |
-| `register_attestor` | self-registration with display URI |
-| `request_validation` | subject owner or third party opens a request |
-| `respond_to_validation` | attestor writes the attestation |
-| `revoke_validation` | original attestor sets `revoked = true` |
+| Instruction | Signer | Effect |
+|---|---|---|
+| `register_namespace(namespace_hash, name, version, schema_uri)` | creator | Create `CapabilityNamespace` PDA |
+| `register_attestor(display_name_uri)` | attestor | Create `AttestorProfile` PDA for the signer |
+| `request_validation(subject_asset, capability_hash, claim_uri_hash, deadline)` | requester (subject's owner OR third party) | Create `ValidationRequest` PDA |
+| `respond_to_validation(subject_asset, capability_hash, claim_payload_hash, claim_uri_hash, expires_at)` | attestor + payer | Create `ValidationAttestation` PDA |
+| `revoke_validation` | original attestor | Set `revoked = true`, `revoked_at = clock.slot`, store `revocation_reason_hash` |
+
+The v1 trust model is "attestor signs the transaction"; the tx signature itself authenticates the attestor. The 64-byte `attestor_signature` field on `ValidationAttestation` is reserved for v1.1+ Ed25519 sysvar verification (per Quantu's `set_agent_wallet` pattern at `identity/instructions.rs:506-541`), which adds non-repudiation against future key compromise.
+
+## State accounts
+
+### `CapabilityNamespace`
+
+```rust
+#[account]
+pub struct CapabilityNamespace {
+    pub namespace_hash: [u8; 32], // SHA256(name_utf8) — self-reference
+    pub name: String,             // ≤ 32 bytes; min 3; no ':' allowed
+    pub version: String,          // ≤ 16 bytes (e.g., "v1")
+    pub schema_uri: String,       // ≤ 160 bytes (IPFS / HTTP)
+    pub registered_at: u64,
+    pub creator: Pubkey,
+    pub bump: u8,
+}
+```
+
+PDA seeds: `["capability", namespace_hash]`. The colon character is forbidden in `name` (`NamespaceColonForbidden`) so namespace strings can be packed into URIs without escaping. Anyone can register; rent (~0.0023 SOL) is the economic deterrent.
+
+Ten canonical v1 namespaces are seeded on devnet: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+### `AttestorProfile`
+
+```rust
+#[account]
+pub struct AttestorProfile {
+    pub attestor: Pubkey,                    // self-reference
+    pub display_name_uri: String,            // ≤ 100 bytes
+    pub total_attestations: u64,             // counter, all-time
+    pub total_revoked_by_attestor: u64,      // self-revoked
+    pub total_revoked_externally: u64,       // reserved for v1.1+ external revoke
+    pub registered_at: u64,
+    pub bump: u8,
+}
+```
+
+PDA seeds: `["attestor", attestor_pubkey]`. Self-registered (permissionless). `total_attestations` increments on each `respond_to_validation`; `total_revoked_by_attestor` increments on `revoke_validation`. v1.1+ adds `staked_amount` for stake-weighted scoring; v2 adds slashing.
+
+### `ValidationRequest`
+
+```rust
+#[account]
+pub struct ValidationRequest {
+    pub subject_asset: Pubkey,
+    pub capability_hash: [u8; 32],
+    pub requester: Pubkey,        // subject's owner OR any third party
+    pub claim_uri_hash: [u8; 32], // SHA256 of off-chain claim URI
+    pub created_at: u64,
+    pub deadline: u64,            // slot after which the request is "abandoned"
+    pub bump: u8,
+}
+```
+
+PDA seeds: `["request", subject_asset, capability_hash, requester]`. Off-chain attestors discover open requests via the `RequestCreated` event; the PDA itself is just an audit-trail record. Non-responded requests past `deadline` are abandoned.
+
+### `ValidationAttestation` — the headline read target
+
+```rust
+#[account]
+pub struct ValidationAttestation {
+    pub subject_asset: Pubkey,            // off  8..40   (parser: 8)
+    pub capability_hash: [u8; 32],        // off 40..72   (parser: 40)
+    pub attestor: Pubkey,                 // off 72..104  (parser: 72)
+    pub claim_payload_hash: [u8; 32],     // off 104..136
+    pub attestor_signature: [u8; 64],     // off 136..200 — Ed25519 sig (v1.1+)
+    pub issued_at: u64,                   // off 200..208
+    pub expires_at: u64,                  // off 208..216 (parser: 208) — 0 = never
+    pub revoked: bool,                    // off 216      (parser: 216)
+    pub revoked_at: u64,                  // off 217..225
+    pub revocation_reason_hash: [u8; 32], // off 225..257
+    pub claim_uri_hash: [u8; 32],         // off 257..289
+    pub bump: u8,                         // off 289
+}
+```
+
+PDA seeds: `["attestation", subject_asset, capability_hash, attestor]`. Account size: 290 bytes.
+
+This is the PDA PolicyVault's `RequireValidation` policy reads at fixed byte offsets via [`ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs). Field declaration order is **load-bearing** — reordering fields silently breaks PolicyVault's reads.
 
-The program source currently exposes five instructions. The docs reserve the sixth slot for the next attestor-management extension.
+## Capability namespace + hash
 
-## Attestation message
+Capabilities are addressed by their SHA-256 hash, not their string name. The v1 PolicyVault parser only knows `capability_hash`; the human-readable name lives in `CapabilityNamespace.name` for off-chain display.
 
-The response path uses a domain-separated message:
+```ts
+import { sha256 } from "@noble/hashes/sha256";
+
+const name = "kyc.tier-1.v1";
+const capability_hash = sha256(new TextEncoder().encode(name));
+// → 366c075140aa69746625d4b733b55e267fc5c28387fd6d1c24901976ee3ddc42
+```
 
-```txt
-AGENTTRUST_ATTEST || subject || capability || payload || expires
+`MAX_NAME_LEN = 32` constrains namespace names. The playbook-level descriptive labels in `docs/plan/research/06-validation-registry-class.md` (e.g., `kyc.tier-1.v1.identity-verified`) decompose to these on-chain category names plus the JSON `description` field.
+
+## Attestation message — domain separation
+
+Per Phase D, the attestation message that attestors sign in v1.1+ is domain-separated:
+
+```
+AGENTTRUST_ATTEST || subject_asset || capability_hash || claim_payload_hash || expires_at
 ```
 
-PolicyVault does not trust arbitrary attestations. `RequireValidation` checks the subject, capability hash, expiry, revoked flag, and allowed attestor list.
+In v1, the same attestor signs the Solana transaction containing `respond_to_validation`; the tx signature serves as the authentication signal. v1.1+ migrates to Ed25519 sysvar verify so a future attestor-key compromise cannot retroactively forge attestations.
+
+## Sybil-resistance model
+
+Permissionless registration plus opinionated downstream filtering. Anyone can register a namespace or an attestor; PolicyVault decides per-policy which attestors to trust via `accepted_attestors[]`. 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.
+
+This is the only model that scales with the number of facilitators. Global gatekeeping (a central allow-list of "approved attestors") would either be too lax (admit too many) or too tight (block niche attestors with valid use cases). Local trust devolves the policy decision to the integrator who owns the cap-set their users care about.
+
+## Revocation — audit-trail-preserving
+
+`revoke_validation` does not delete the `ValidationAttestation` PDA. It sets `revoked = true`, writes `revoked_at = clock.slot`, and stores a `revocation_reason_hash`. Downstream readers (PolicyVault) treat `revoked == true` as `Deny(AttestationRevoked)` (DenyReason code `13`). The audit trail — including `issued_at`, `expires_at`, `claim_uri_hash`, and the original `attestor_signature` (v1.1+) — stays on chain.
+
+This is the ERC-8004 spec posture: revocations preserve history rather than erase it.
+
+## Live evidence
+
+Four-signature chained-validation trace on devnet (`gate_payment` → `request_validation` → `respond_to_validation` → `gate_payment`): [Verification → Chained validation](/verification/chained-validation). Ten capability namespaces seeded: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+## Events
 
-## Byte fields consumed by PolicyVault
+| Event | Fields |
+|---|---|
+| `NamespaceRegistered` | `namespace_hash`, `creator` |
+| `AttestorRegistered` | `attestor` |
+| `RequestCreated` | `subject_asset`, `capability_hash`, `requester`, `claim_uri_hash`, `deadline` |
+| `AttestationCreated` | `subject_asset`, `capability_hash`, `attestor`, `expires_at`, `issued_at` |
+| `AttestationRevoked` | `subject_asset`, `capability_hash`, `attestor`, `revoked_at`, `revocation_reason_hash` |
 
-| Field | Offset |
-| --- | --- |
-| subject asset | `8` |
-| capability hash | `40` |
-| attestor | `72` |
-| expires at slot | `208` |
-| revoked flag | `216` |
+## Source
 
-Source: `programs/validation-registry/src/lib.rs`.
+- Program entry: [`programs/validation-registry/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/lib.rs)
+- State: [`state/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/validation-registry/src/state)
+- Instructions: [`instructions/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/validation-registry/src/instructions)
+- PolicyVault byte-offset parser: [`policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs)

package/dist/embedded-docs/reference/byte-offset-reference.mdx

@@ -1,20 +1,109 @@
 ---
 title: Byte-offset reference
-description: Fixed offsets used by AgentTrust cross-program readers.
+description: Fixed offsets used by AgentTrust's manual byte-offset readers — Quantu AtomStats and AgentTrust ValidationAttestation.
 ---
 
-`In progress`
+PolicyVault reads two foreign PDAs through byte-precise parsers rather than Borsh deserialization. Schema-version canaries fail loud rather than silently misread fields if the upstream layout changes.
 
-| Account | Field | Offset |
-| --- | --- | --- |
-| `AtomStats` | `risk_score` | `549` |
-| `AtomStats` | `trust_tier` | `551` |
-| `AtomStats` | `confidence` | `557..558` |
-| `ValidationAttestation` | `subject` | `8` |
-| `ValidationAttestation` | `capability` | `40` |
-| `ValidationAttestation` | `attestor` | `72` |
-| `ValidationAttestation` | `expires` | `208` |
-| `ValidationAttestation` | `revoked` | `216` |
+Sources: [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs), [`programs/policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs).
 
-Sources: [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs), [`programs/policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs)
+## Quantu `AtomStats` (561 bytes)
 
+Pinned to commit `bfb09ad`. Account-data-relative offsets — the 8-byte Borsh discriminator at `0..8` is verified via owner check, not by re-parsing.
+
+| Offset | Width | Field | Notes |
+|---:|---:|---|---|
+| `549` | u8 | `risk_score` | 0..=255 — lower is better |
+| `551` | u8 | `tier_immediate` | 0..=4 — v1 demo default; what `CounterpartyTier` reads in `GATE_MODE_IMMEDIATE` |
+| `555` | u8 | `tier_confirmed` | 0..=4 — post-vesting; production policies prefer this via `GATE_MODE_CONFIRMED` |
+| `557` | u16 LE | `confidence` | 0..=10000 (basis points) |
+| `560` | u8 | `schema_version` | **canary** — must equal 1; mismatch → `Deny(AtomStatsSchemaMismatch)` |
+
+Constants:
+
+| Symbol | Value |
+|---|---:|
+| `ATOM_STATS_SIZE` | 561 |
+| `ATOM_TIER_MAX` | 4 |
+| `ATOM_STATS_SCHEMA_VERSION_EXPECTED` | 1 |
+| `ATOM_ENGINE_ID` (devnet) | `AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF` |
+| `ATOM_ENGINE_ID` (mainnet) | `AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb` |
+
+A tier byte above `ATOM_TIER_MAX` with `schema_version == 1` implies tampering or an undeclared spec change — the parser fails with `AtomStatsSchemaMismatch` rather than silently clamp.
+
+## AgentTrust `ValidationAttestation` (290 bytes)
+
+Account-data-relative offsets. Field declaration order is **load-bearing** — reordering fields silently breaks PolicyVault's reads.
+
+| Offset | Width | Field | Notes |
+|---:|---:|---|---|
+| `8` | Pubkey | `subject_asset` | The payee this attestation is about |
+| `40` | [u8; 32] | `capability_hash` | SHA-256 of the namespace name |
+| `72` | Pubkey | `attestor` | The key that signed `respond_to_validation` |
+| `104` | [u8; 32] | `claim_payload_hash` | not read by v1 policy |
+| `136` | [u8; 64] | `attestor_signature` | reserved for v1.1+ Ed25519 sysvar verify |
+| `200` | u64 LE | `issued_at` | not read by v1 policy |
+| `208` | u64 LE | `expires_at` | 0 = never expires |
+| `216` | bool | `revoked` | `revoked == true` → `Deny(AttestationRevoked)` |
+| `217` | u64 LE | `revoked_at` | not read by v1 policy |
+| `225` | [u8; 32] | `revocation_reason_hash` | not read by v1 policy |
+| `257` | [u8; 32] | `claim_uri_hash` | not read by v1 policy |
+| `289` | u8 | `bump` | not read by v1 policy |
+
+Constants:
+
+| Symbol | Value |
+|---|---:|
+| `VALIDATION_ATTESTATION_SIZE` | 290 |
+| `VA_SUBJECT_ASSET_OFFSET` | 8 |
+| `VA_CAPABILITY_HASH_OFFSET` | 40 |
+| `VA_ATTESTOR_OFFSET` | 72 |
+| `VA_EXPIRES_AT_OFFSET` | 208 |
+| `VA_REVOKED_OFFSET` | 216 |
+| `VALIDATION_REGISTRY_ID` (devnet) | `Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv` |
+
+## AgentTrust `PolicyAccount` (240 bytes — own program)
+
+PolicyVault's own state. Field offsets matter for the playbook contract; readers (the composer, the SDK's `parseGateDecision`) use the Anchor-generated decoder rather than byte offsets, but the layout is documented for downstream tooling.
+
+| Offset | Width | Field |
+|---:|---:|---|
+| `8` | Pubkey | `payer_agent_asset` |
+| `40` | u32 | `policy_id` |
+| `44` | u8 | `bump` |
+| `48` | u8 | `enabled_kinds_bitmask` |
+| `49` | u8 | `gate_mode` |
+| `50` | u64 | `spending_per_tx_max` |
+| `58` | u64 | `spending_daily_max` |
+| `66` | u64 | `spending_weekly_max` |
+| `74` | u64 | `spending_today_used` |
+| `82` | u64 | `spending_week_used` |
+| `90` | u64 | `spending_today_anchor` |
+| `98` | u64 | `spending_week_anchor` |
+| `106` | u64 | `velocity_window_secs` |
+| `114` | u64 | `velocity_max_in_window` |
+| `122` | u64 | `velocity_tier0_decay_factor` |
+| `130` | u8 | `min_counterparty_tier` |
+| `131` | u8 | `max_risk_score` |
+| `132` | u16 | `min_confidence` |
+| `134` | u8 | `default_unrated_treatment` |
+| `135` | [u8; 32] | `required_capability_hash` |
+| `167` | [Pubkey; 2] | `accepted_attestors` |
+| `231` | u8 | `scope_kind` |
+| `232` | [u8; 8] | `_reserved` |
+
+Source: [`programs/policy-vault/src/state/policy_account.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_account.rs).
+
+## Read next
+
+<Cards>
+  <Card title="Discriminator constants" href="/reference/discriminator-constants">
+    Quantu give_feedback discriminator + AgentTrust PDA seed prefixes.
+  </Card>
+  <Card title="CounterpartyTier policy" href="/programs/policy-vault/counterparty-tier-policy">
+    What the AtomStats reader feeds into.
+  </Card>
+  <Card title="RequireValidation policy" href="/programs/policy-vault/require-validation-policy">
+    What the ValidationAttestation reader feeds into.
+  </Card>
+</Cards>

package/dist/embedded-docs/reference/capability-namespaces.mdx

@@ -0,0 +1,56 @@
+---
+title: Capability namespaces
+description: The ten canonical v1 capability namespaces seeded on devnet — auto-generated from examples/attestor-demo/devnet-namespaces.json.
+---
+
+The ten canonical v1 capability namespaces seeded on AgentTrust's `validation-registry` on Solana devnet. PolicyVault gates against `capability_hash = SHA-256(name)` per [PolicyAccount byte 135..167](/programs/policy-vault/require-validation-policy).
+
+How to use one in a policy: [Integration → Capability namespaces](/integration-guides/capability-namespaces). How to register your own: [Custom attestor](/integration-guides/custom-attestor).
+
+{/* BEGIN AUTO-GEN: namespaces */}
+
+> Auto-generated from `examples/attestor-demo/devnet-namespaces.json` on 2026-05-07T15:08:37.863Z.
+> Network: `solana-devnet`. Program: `Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`. Count: 10.
+
+| Name | Description | Capability hash (SHA-256, prefix) | PDA |
+|---|---|---|---|
+| `kyc.tier-1.v1` | Identity-verified individual (basic KYC). _(newly-registered)_ | [`366c075140aa…`](https://explorer.solana.com/tx/5jBmV36b89kMxzqPPtzFTWJD12vvB6TznMBGwZWtKNSApfuPzoPmJVAG2ed8bRWMkTfZ6QF3Ks21KESaTxU7Mb1W?cluster=devnet) | [`4ryEbb5iSi…`](https://explorer.solana.com/address/4ryEbb5iSiXHN2bJ59s9Pjdi2xxRkty1WohaRTqUt8wW?cluster=devnet) |
+| `kyc.tier-2.v1` | Identity + address verified. _(newly-registered)_ | [`2ad4289070be…`](https://explorer.solana.com/tx/3tBAqxVnyqDj23P1Jyk1atdunUrsm4M54g4NDUKgAFJyeMLjfbpXe6ZR6QKcBMmRpA4HxfTVbVnD3pavcQtB3R81?cluster=devnet) | [`HdAABUX5oj…`](https://explorer.solana.com/address/HdAABUX5ojFZXocxSbTwvdNLXHGLaHnqCrKSKpeKXGCv?cluster=devnet) |
+| `kyc.tier-3.v1` | Enhanced due diligence (regulated counterparties). _(newly-registered)_ | [`8fdd7707b57b…`](https://explorer.solana.com/tx/3LH2WNYn6ifYaXmF7WPcD5bsJB9T3HT3NgpeX13Jf1jg6eyfjQG8PBRqQjBQxT2HexTgzEvRJjcmonsRPXVmwGMp?cluster=devnet) | [`6gjTXCJE4q…`](https://explorer.solana.com/address/6gjTXCJE4qWybYGjTAg5ckYWBgBtt4ebvr39uU5YK5xL?cluster=devnet) |
+| `audit.smart-contract.v1` | Audit attestation against a deployed program. _(newly-registered)_ | [`e61adaa34c65…`](https://explorer.solana.com/tx/319AFhK4wpWmhauHqsVUoqUdx3gadHcGsMNyAvt7Hgoau7ceAohViHAGRtvLP3PStF1Sqz5UkSCJy11nAqNJrRQa?cluster=devnet) | [`HygALr1ZSq…`](https://explorer.solana.com/address/HygALr1ZSqrYZTLBQUQ97vMSzAiuZRpKYovRhfyGtKkF?cluster=devnet) |
+| `audit.attestor-firm.v1` | Per-firm audit identity (Halborn / OtterSec / etc.). _(newly-registered)_ | [`17926cb4f324…`](https://explorer.solana.com/tx/5KQG73FhBjixhaK3jE3XvsVJh4Xcd8kWMWphwuj9dHkTLTMhxwYB4BMzGw1TF8ZGnY6ZXTLY4CbeBZhF6nTobrNo?cluster=devnet) | [`A5rrMRYxez…`](https://explorer.solana.com/address/A5rrMRYxezaNUnSgqyyNjJUqHf4TH7GKNsvUifWjUESi?cluster=devnet) |
+| `model-card.v1` | LLM model-version provenance attestation. _(newly-registered)_ | [`d90347d0a0a7…`](https://explorer.solana.com/tx/gmHvwe6NBB6vjMNPrMppfm2SVjvhizubUX8pACBJTZZ8rnbRaBFaLYuGqoa4TtApK2JqDFrUggZj8WS87xXGds6?cluster=devnet) | [`DZ7eneZtKs…`](https://explorer.solana.com/address/DZ7eneZtKsN39q771ruHvBXoTUDRzxKqDipTLbeRGa4o?cluster=devnet) |
+| `jurisdiction.v1` | Regulatory-jurisdiction stamp (EU MiCA, US, etc.). _(newly-registered)_ | [`ce2818907881…`](https://explorer.solana.com/tx/5fUkGfziyLWbMeqp6pfZXrWMBf2mc3VzMZEsHUYjsynvANQSzjQtAkakVxXJNvPPQaCBEg8YnErk82VLbSHxSUMV?cluster=devnet) | [`Cd4sp8isN3…`](https://explorer.solana.com/address/Cd4sp8isN3CF8KiRchDNoMhsVERSpswEnufvBR21Jrnu?cluster=devnet) |
+| `compliance.payments.v1` | Payment-network compliance attestation (Mastercard FACT-aligned, etc.). _(newly-registered)_ | [`0a8984a645e7…`](https://explorer.solana.com/tx/5B3ZfMMAjDSyrTnhGzXCCNcdg4yEeRepb8v1d8fK299WiyJpex5RbiW7ahha1VxPJfVSixyfXtb7R4wSFfd11Wm4?cluster=devnet) | [`Cn54CpSdfr…`](https://explorer.solana.com/address/Cn54CpSdfrME7epZ2VTSwhuTbcwH3ZttpcwjZADc5yrZ?cluster=devnet) |
+| `agent-source.v1` | Provenance: which dev shop authored the agent. _(newly-registered)_ | [`2328df178dc6…`](https://explorer.solana.com/tx/52mqFEk5gpytgYjhsq4j7yML4tEcxg7jQhwb5Z6xqmx3cecX8vXP4C5NN6PRyXPSGtnTeSVZ8nBVaaYimU4NP4nH?cluster=devnet) | [`DqSwaqENQh…`](https://explorer.solana.com/address/DqSwaqENQhjPUajxfmzsjTcfTcnNXtNN22f3kYyAHvSJ?cluster=devnet) |
+| `usdc-payment-policy.v1` | USDC payment policy capability — Phase D attestor demo. _(already-registered)_ | `a968ecd0b93d…` | [`34gonn86Fj…`](https://explorer.solana.com/address/34gonn86FjxzXZMGd43RSvQVyH1r6PrGV9xnHXjjkEwR?cluster=devnet) |
+
+> Names are bounded by `MAX_NAME_LEN = 32` per [`programs/validation-registry/src/instructions/register_namespace.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/validation-registry/src/instructions/register_namespace.rs). PDA seeds: `["capability", capability_hash]`.
+
+{/* END AUTO-GEN: namespaces */}
+
+## Reproduce
+
+The seeded namespace set is captured in [`examples/attestor-demo/devnet-namespaces.json`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/attestor-demo/devnet-namespaces.json) — the source of truth this page is auto-generated from.
+
+Re-run the seed script (idempotent — already-registered namespaces no-op):
+
+```bash
+pnpm --filter ./examples/attestor-demo run seed:namespaces
+```
+
+The script registers any missing namespaces from the canonical v1 set; cost is ~0.0023 SOL per fresh registration.
+
+## Read next
+
+<Cards>
+  <Card title="Capability namespaces (walkthrough)" href="/integration-guides/capability-namespaces">
+    Register a new namespace + gate a policy against it.
+  </Card>
+  <Card title="ValidationRegistry" href="/programs/validation-registry">
+    The program that owns these PDAs.
+  </Card>
+  <Card title="Chained validation" href="/verification/chained-validation">
+    The four-sig devnet trace exercising one of these namespaces (`usdc-payment-policy.v1`).
+  </Card>
+</Cards>