@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/mcp/prompts.mdx

@@ -0,0 +1,90 @@
+---
+title: Prompts
+description: Three guided MCP workflows — audit a payment, set up an agent, explain a failure. Each composes multiple tool calls into a structured procedure.
+---
+
+MCP prompts are reusable, parameterised templates that the server returns in response to `prompts/get`. The client (Claude Desktop, Cursor, OpenAI Agents SDK) presents the prompt's messages to the model, which then drives the tool calls. Prompts encode the right *order* of tool calls for common workflows.
+
+Source: [`mcp/src/prompts/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/prompts).
+
+## Three prompts
+
+| Name | What it walks the user through |
+|---|---|
+| [`agenttrust_audit_payment`](#agenttrust_audit_payment) | Simulate a payment, read the policy, read the payee's reputation, surface the decision |
+| [`agenttrust_setup_agent`](#agenttrust_setup_agent) | Bootstrap an agent's `PolicyAuthority` → `KillSwitchState` → first `PolicyAccount` |
+| [`agenttrust_explain_failure`](#agenttrust_explain_failure) | Given a failed payment's reason code, explain root cause + remediation |
+
+## `agenttrust_audit_payment`
+
+Required args: `payer_agent`, `payee_agent`, `amount`, `mint`, `policy_id`. Optional: `caller`.
+
+The prompt walks the model through:
+
+1. `agenttrust_get_policy({ agent_asset: payer_agent, policy_id })` — read the spending caps, velocity threshold, counterparty tier requirement, required capability.
+2. `agenttrust_get_quantu_reputation({ agent_asset: payee_agent })` — read the payee's tier, risk, confidence.
+3. `agenttrust_simulate_payment({ caller, payer_agent, payee_agent, amount, mint, policy_id })` — run the gate.
+4. Compare the simulation result to the policy thresholds + payee reputation. Surface `Allow`, `Deny(reason)`, or `RequireValidation(capability)` with the relevant numbers.
+
+Use case: "Audit this payment before I send it." The model produces a structured explanation of the decision rather than a yes/no answer.
+
+## `agenttrust_setup_agent`
+
+Required args: `agent_asset`, `use_case`. The `use_case` is free-text — the prompt uses it to suggest reasonable defaults for the policy fields (per-tx cap, velocity window, counterparty tier minimum).
+
+The prompt walks the model through:
+
+1. `agenttrust_get_killswitch({ agent_asset })` — check whether `PolicyAuthority` and `KillSwitchState` exist.
+2. If absent, instruct the model to call `init_authority` (off-band, since v1 doesn't expose this as an MCP write tool).
+3. `agenttrust_init_policy({ agent_asset, policy_id: 1, enabled_kinds_bitmask: 0b11111, … })` — initialise the first policy with use-case-tailored defaults.
+4. Confirm the result by calling `agenttrust_get_policy`.
+
+Use case: "I just got my Quantu agent identity. Set up a basic AgentTrust policy." The prompt + the write tools land a working policy in three or four turns.
+
+## `agenttrust_explain_failure`
+
+Required args: `reason_code` (1..15). Optional: `payer_agent`, `payee_agent`, `policy_id`.
+
+The prompt walks the model through:
+
+1. `agenttrust_explain_decision({ reason_code })` — translate to canonical name + remediation hint.
+2. If the optional context is present, run the relevant lookup (`get_quantu_reputation`, `get_velocity`, `get_killswitch`, `get_validation_attestation`) to inspect the actual on-chain state that drove the deny.
+3. Surface the contradiction in plain language ("the policy requires `min_counterparty_tier = 3` but the payee's `tier_immediate = 1`").
+
+Use case: "Why did my last payment fail with reason code 6?" The prompt produces an explanation grounded in real on-chain state, not training-data guesses.
+
+## How clients invoke prompts
+
+```ts
+// Pseudocode — the actual API depends on the MCP client.
+const prompts = await mcp.request("prompts/list");
+// → [{ name: "agenttrust_audit_payment", description, arguments }, …]
+
+const audit = await mcp.request("prompts/get", {
+  name:      "agenttrust_audit_payment",
+  arguments: {
+    payer_agent: "5Pfa…K8y",
+    payee_agent: "C9pY…B3dR",
+    amount:      "1000000",
+    mint:        "EPjF…Dt1v",
+    policy_id:   1,
+    caller:      "4tSE…hRG",
+  },
+});
+// → { messages: [{ role: "user", content: { type: "text", text: "Walk me through auditing this payment…" } }, … ] }
+```
+
+The model then picks tools to call, the client surfaces the tool results back to the model, and the prompt's structure produces a grounded answer.
+
+In Claude Desktop, prompts appear as slash commands when an MCP server is connected. Type `/agenttrust_audit_payment` in chat → the UI prompts for the required arguments → the model executes the workflow.
+
+## Validation
+
+Phase M validated all three prompts via direct `prompts/get` calls. All three return non-empty `messages` arrays with structured user prompts referencing the right tools. Missing-argument probes return clean `-32603 missing required argument` errors. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) §M1.5.
+
+Phase P verified `agenttrust_explain_failure` end-to-end with Claude `sonnet` driving the workflow against live devnet state — the model called `agenttrust_explain_decision(6)` then `agenttrust_get_killswitch` to inspect the actual policy fields, and produced a remediation in plain language.
+
+## Source
+
+- Prompts: [`mcp/src/prompts/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/prompts)
+- Server wiring: [`mcp/src/server.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/server.ts)

package/dist/embedded-docs/mcp/resources.mdx

@@ -0,0 +1,115 @@
+---
+title: Resources
+description: Four MCP resource URIs — devnet program manifest, docs corpus mirror, demo source files. Path-traversal-safe, MIME-typed, MCP-list-friendly.
+---
+
+The MCP server exposes four `resources/list`-able URIs. Resources are read-only by design; writes happen through tools.
+
+Source: [`mcp/src/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/resources).
+
+## URI manifest
+
+| URI scheme | Mime type | Content |
+|---|---|---|
+| `agenttrust://devnet/programs` | `application/json` | Deployed program IDs + Explorer URLs for the active cluster |
+| `agenttrust://docs/<rel-path>` | `text/markdown` | Each MDX page in the docs corpus exposed individually |
+| `agenttrust://examples/pay-sh-demo/<rel-path>` | `text/x-typescript` / `text/markdown` | Pay.sh demo source files |
+| `agenttrust://examples/attestor-demo/<rel-path>` | `text/x-typescript` / `text/markdown` | Attestor demo source files |
+
+## Devnet program manifest
+
+```json
+{
+  "uri": "agenttrust://devnet/programs",
+  "mimeType": "application/json"
+}
+```
+
+Returns:
+
+```json
+{
+  "network": "solana-devnet",
+  "programs": {
+    "policy_vault": {
+      "id": "8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR",
+      "explorerUrl": "https://explorer.solana.com/address/8Y6f…QTR?cluster=devnet"
+    },
+    "trustgate": {
+      "id": "HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N",
+      "explorerUrl": "https://explorer.solana.com/address/HF8z…ih2N?cluster=devnet"
+    },
+    "validation_registry": {
+      "id": "Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv",
+      "explorerUrl": "https://explorer.solana.com/address/Cx4R…Khtv?cluster=devnet"
+    }
+  }
+}
+```
+
+## Docs corpus mirror
+
+Every MDX page under [`docs-site/content/docs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/docs-site/content/docs) is exposed as an individual resource. Example URIs:
+
+```
+agenttrust://docs/index
+agenttrust://docs/architecture
+agenttrust://docs/programs/policy-vault/index
+agenttrust://docs/sdk/atomic-tx-invariant
+agenttrust://docs/verification/live-evidence
+```
+
+The resource body is the rendered markdown text (frontmatter included). LLM clients use `agenttrust_docs` (a discovery tool with full-text search) to find the right resource, then fetch it via `resources/read`.
+
+## Demo source mirrors
+
+The Pay.sh demo and the attestor demo are bundled in the npm tarball as of 0.2.3. URIs:
+
+```
+agenttrust://examples/pay-sh-demo/README.md
+agenttrust://examples/pay-sh-demo/src/index.ts
+agenttrust://examples/pay-sh-demo/src/middleware.ts
+agenttrust://examples/pay-sh-demo/devnet-counterparties.json
+
+agenttrust://examples/attestor-demo/README.md
+agenttrust://examples/attestor-demo/scripts/devnet-chained-validation.ts
+agenttrust://examples/attestor-demo/devnet-namespaces.json
+```
+
+Use case: an LLM asks "show me the Pay.sh demo source" and the tool returns the actual file contents rather than synthesizing a stale paraphrase from training data.
+
+## Path-traversal safety
+
+All resource URIs go through a path-normalization step before file reads. Probes like `agenttrust://docs/../../etc/passwd` return:
+
+```json
+{
+  "error": {
+    "code":    -32603,
+    "message": "unknown resource URI"
+  }
+}
+```
+
+Same protection on the `examples/` URIs. Source: [`mcp/src/resources/docs.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/resources/docs.ts) — the indexer normalises every path against the corpus root before serving bytes.
+
+Phase M validated this against a deliberate traversal probe — clean error, no escape. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) §M1.4.
+
+## How clients use resources
+
+```ts
+// Pseudocode — actual API depends on the MCP client.
+const list = await mcp.request("resources/list");
+// → [{ uri: "agenttrust://devnet/programs", … }, { uri: "agenttrust://docs/index", … }, …]
+
+const programs = await mcp.request("resources/read", { uri: "agenttrust://devnet/programs" });
+// → { contents: [{ uri, mimeType: "application/json", text: "{ …JSON… }" }] }
+```
+
+Claude Desktop and Cursor surface resources in their model-context UI — the user can attach a resource to the conversation and the LLM reads it directly, no tool round-trip needed.
+
+## Source
+
+- Resource handlers: [`mcp/src/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/resources)
+- Server wiring: [`mcp/src/server.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/server.ts)
+- Path-traversal tests: [`mcp/test/resources/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/test/resources)

package/dist/embedded-docs/mcp/tools.mdx

@@ -0,0 +1,156 @@
+---
+title: Tools
+description: All 18 MCP tools — 10 read, 5 write, 3 discovery — with input/output shape and live devnet examples.
+---
+
+Each tool has a stable Zod schema. Input arguments are documented per tool below. Every write tool surfaces the resulting `txSignature` plus a Solana Explorer URL in its response.
+
+Source: [`mcp/src/tools/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools).
+
+## Read (10 tools — no signer required)
+
+| Tool | Input | Returns |
+|---|---|---|
+| [`agenttrust_get_policy`](#agenttrust_get_policy) | `agent_asset`, `policy_id` | Decoded `PolicyAccount` PDA — every spending cap, velocity threshold, counterparty tier requirement, required capability hash |
+| [`agenttrust_list_policies`](#agenttrust_list_policies) | `agent_asset` | Lightweight summary of all policies registered for an agent |
+| [`agenttrust_simulate_payment`](#agenttrust_simulate_payment) | `caller`, `payer_agent`, `payee_agent`, `amount`, `mint`, `policy_id` | `Allow` / `Deny(reasonCode, reasonName)` / `RequireValidation(capabilityHash)` |
+| [`agenttrust_get_killswitch`](#agenttrust_get_killswitch) | `agent_asset` | `KillSwitchState` + `PolicyAuthority` decoded |
+| [`agenttrust_get_velocity`](#agenttrust_get_velocity) | `agent_asset`, `policy_id` | `VelocityLedger` — sliding-window cumulative spend |
+| [`agenttrust_get_feedback_log`](#agenttrust_get_feedback_log) | `payment_id_hash` (32-byte hex) | `FeedbackEmissionLog` PDA |
+| [`agenttrust_get_quantu_reputation`](#agenttrust_get_quantu_reputation) | `agent_asset` | Quantu `AtomStats` decoded — `tierImmediate`, `tierConfirmed`, `riskScore`, `confidence`, `schemaVersion` |
+| [`agenttrust_get_validation_attestation`](#agenttrust_get_validation_attestation) | `subject_asset`, `capability_name` OR `capability_hash`, `attestor` | Every `ValidationAttestation` PDA matching the filter |
+| [`agenttrust_list_facilitators`](#agenttrust_list_facilitators) | — | Active facilitator adapters (Pay.sh / Dexter / atxp / MCPay) + ship status |
+| [`agenttrust_demo_state`](#agenttrust_demo_state) | — | Three pre-warmed devnet counterparties used by `examples/pay-sh-demo` |
+
+### `agenttrust_get_policy`
+
+Decodes the `PolicyAccount` PDA at `["policy", agent_asset, policy_id_le]`. Returns every byte: `enabled_kinds_bitmask`, `gate_mode`, all spending fields, all velocity fields, `min_counterparty_tier`, `max_risk_score`, `min_confidence`, `default_unrated_treatment`, `required_capability_hash` (hex), `accepted_attestors[]`, `scope_kind`. Non-existent policies return `exists: false`.
+
+### `agenttrust_list_policies`
+
+Lightweight summary across `policy_id ∈ {1..10}` for the given agent. Use `get_policy` for the full decode of a specific policy.
+
+### `agenttrust_simulate_payment`
+
+Read-only `gate_payment` simulation. Same semantics as the SDK's [`gatePayment()`](/sdk/gate-payment) — invokes the lazy variant (returns decision via Anchor's return-data channel), parses the response into the `GateDecision` union.
+
+`caller` is required; pass any funded base58 pubkey. The simulation tx isn't committed, but Solana requires a fee-payer keypair. As of 0.2.1 the tool surfaces a clear actionable error if `caller` is omitted (was a cryptic `AccountNotFound` before).
+
+### `agenttrust_get_killswitch`
+
+Returns the `KillSwitchState` for the agent's per-agent kill switch (scope_kind = 2, scope_key = agent_asset) plus the `PolicyAuthority` (multisig members + threshold). Useful when debugging "why is this agent paused?".
+
+### `agenttrust_get_velocity`
+
+Decodes the `VelocityLedger` PDA at `["velocity", agent_asset, policy_id_le]`. Returns `cumulative_amount`, `last_commit_slot`, `window_start_slot`. The window-active vs window-expired check (`elapsed >= window_slots`) is a pure-fn evaluation — match the policy's `velocity_window_secs` × `tier_decay(payer_tier) × 2 slots/sec`.
+
+### `agenttrust_get_feedback_log`
+
+`FeedbackEmissionLog` lookup by `payment_id_hash`. The PDA is at `["feedback_log", payment_id_hash]`. Returns `score`, `is_dispute`, `emitted_at_slot` if found, or `exists: false`.
+
+### `agenttrust_get_quantu_reputation`
+
+Decodes Quantu's `AtomStats` at `["atom_stats", agent_asset]`. Returns:
+
+```json
+{
+  "pda":          "4z9RiK6B49QZbmqPM9yNZWgfxYD3tvQ3NETU6X89f5mv",
+  "ownerProgram": "AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF",
+  "ownerMatches": true,
+  "rawByteLen":   561,
+  "reputation": {
+    "tierImmediate":  3,
+    "tierConfirmed":  2,
+    "riskScore":      42,
+    "confidence":     8500,
+    "schemaVersion":  1
+  }
+}
+```
+
+Mirrors the canonical byte offsets from [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs) verbatim — 549 / 551 / 555 / 557 / 560. Fixed in MCP 0.2.6 (Phase Q1) after the schema-version canary at byte 560 + the `tier ≤ 4` range check were added; v0.2.5 had fabricated offsets that returned junk values.
+
+### `agenttrust_get_validation_attestation`
+
+Returns every `ValidationAttestation` PDA matching `(subject_asset, capability_name OR capability_hash)`, optionally filtered by `attestor`. Accepts the friendly capability name (the SDK computes SHA-256 internally) or the 64-char hex hash. Added in 0.2.4 — real LLMs typically have the human-readable name; requiring the digest was a friction point.
+
+### `agenttrust_list_facilitators`
+
+Returns the active adapter set: Pay.sh (live), Dexter (in-flight), atxp (roadmap), MCPay (roadmap). Each entry includes the adapter's wire format hint and ship status.
+
+### `agenttrust_demo_state`
+
+Returns the three pre-warmed devnet counterparties used by `examples/pay-sh-demo`:
+
+| Tier | Asset pubkey | Expected gate decision |
+|---|---|---|
+| 0 (untrusted) | `C9pYqwnCVpwg7MwEbQa4XcmVVYsUcPwqHMYs999KB3dR` | `Deny(CounterpartyTierBelowMin)` |
+| 1 (low-trust) | `9894Sh7F79yDzTi4Pvfm5Jy5VmLpx2XkyhS14BFwpyrd` | `Deny(CounterpartyTierBelowMin)` |
+| 3 (Gold) | `5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y` | `Allow` (with a tier-3 policy) |
+
+The demo state is bundled in the tarball as of 0.2.3 — the published package doesn't need a separate state file.
+
+## Write (5 tools — require `KEYPAIR_B58`)
+
+| Tool | Effect |
+|---|---|
+| [`agenttrust_init_policy`](#agenttrust_init_policy) | Create `PolicyAccount` + `VelocityLedger` for the signer's agent |
+| [`agenttrust_set_killswitch`](#agenttrust_set_killswitch) | Pause / unpause the agent's `KillSwitchState` (lead-only multisig in v1) |
+| [`agenttrust_request_validation`](#agenttrust_request_validation) | Open a `ValidationRequest` PDA |
+| [`agenttrust_respond_to_validation`](#agenttrust_respond_to_validation) | Attestor writes a `ValidationAttestation` PDA |
+| [`agenttrust_emit_feedback`](#agenttrust_emit_feedback) | Facilitator-only `emit_feedback` CPI (signer must equal facilitator) |
+
+### `agenttrust_init_policy`
+
+Required args: `agent_asset`, `policy_id`, `enabled_kinds_bitmask` (e.g., `0b11111` = all five kinds). Optional: every `PolicyAccount` field — defaults are documented in [`programs/policy-vault/src/instructions/init_policy.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/init_policy.rs).
+
+### `agenttrust_set_killswitch`
+
+Required args: `agent_asset`, `paused`. Multisig-gated against `PolicyAuthority` per [KillSwitch policy](/programs/policy-vault/kill-switch-policy). v1 uses single-signer (lead-only) for hackathon-velocity reasons; v1.1+ exercises the full Kani-proven multi-signer path.
+
+### `agenttrust_request_validation`
+
+Required args: `subject_asset`, `claim_uri_hash_hex`, `deadline_slot`. The capability is implied by the active namespace context. Subject's owner OR any third party can open the request; off-chain attestors discover via the `RequestCreated` event.
+
+### `agenttrust_respond_to_validation`
+
+Required args: `subject_asset`, `claim_payload_hash_hex`, `claim_uri_hash_hex`, `expires_at_slot`. The signer (the keypair behind `KEYPAIR_B58`) is the attestor. v1 trust model: tx signature authenticates; v1.1+ adds Ed25519 sysvar verify.
+
+### `agenttrust_emit_feedback`
+
+Required args: `payment_id_hash_hex`, `payee_asset`, `base_collection`, `score`. The signer must equal the facilitator (`FacilitatorSignerMismatch` otherwise). `base_collection` is the value passed to Quantu's `register_agent` — the agent-registry-8004 collection address.
+
+## Discovery (3 tools)
+
+| Tool | Returns |
+|---|---|
+| [`agenttrust_docs`](#agenttrust_docs) | Full-text search over `docs-site/content/docs/` — ranked hits with excerpts |
+| [`agenttrust_facilitator_walkthrough`](#agenttrust_facilitator_walkthrough) | Per-adapter integration walkthrough by name |
+| [`agenttrust_explain_decision`](#agenttrust_explain_decision) | Translate a `DenyReason` code (1..15) into the enum name + remediation hint |
+
+### `agenttrust_docs`
+
+Searches the bundled docs corpus. Returns ranked hits with excerpts. Use case: an LLM asks "what's the atomic-tx invariant?" and the tool surfaces the verification page with a relevant excerpt rather than hallucinating from training data.
+
+The corpus is bundled in the tarball as of 0.2.3. `MCP_DOCS_DIR` env var lets tests point at a different root.
+
+### `agenttrust_facilitator_walkthrough`
+
+Returns the canonical guide for a named facilitator (`pay-sh`, `dexter`, `atxp`, `mcpay`, or `x402`). Falls back to the generic adapters guide for unknown names. Use case: an LLM asks "walk me through adding a new facilitator" and the tool returns the contract page.
+
+### `agenttrust_explain_decision`
+
+Maps a `DenyReason` code (`1..15`) to the canonical name + remediation hint. Same data the [Reference → DenyReason codes](/reference/deny-reason-codes) page surfaces, but tool-shaped for LLM consumption.
+
+## Validation status
+
+Phase M comprehensive E2E (2026-05-07): all 18 tools present, 10/10 read tools return live devnet state with clickable Explorer URLs, 6/6 PDAs cross-validated against on-chain ground truth, 4/4 Explorer URLs return HTTP 200. Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md).
+
+Phase P real-LLM tool-routing (2026-05-08): 7/10 strict pass on natural-language scenarios via Claude `sonnet`. The three false negatives were context-gathering artefacts (the LLM called `agenttrust_demo_state` first to gather context, then the expected tool); a less agentic client would score 9/10. Full report: [`docs/proofs/phase-p-llm-routing.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-p-llm-routing.md).
+
+## Source
+
+- Read tools: [`mcp/src/tools/read/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/read)
+- Write tools: [`mcp/src/tools/write/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/write)
+- Discovery tools: [`mcp/src/tools/discovery/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp/src/tools/discovery)
+- Tool aggregator: [`mcp/src/tools/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/tools/index.ts)

package/dist/embedded-docs/programs/policy-vault/composer.mdx

@@ -0,0 +1,117 @@
+---
+title: Composer
+description: The pure-Rust orchestration that ties the five policy kinds together with fail-fast semantics and Allow-only state mutation.
+---
+
+`compose_decision` is the single function that runs every policy and returns the gate's verdict. The Anchor handlers (`gate_payment`, `gate_payment_strict`) are thin wrappers around it.
+
+Source: [`programs/policy-vault/src/policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs).
+
+## Signature
+
+```rust
+pub fn compose_decision(input: ComposerInput) -> ComposerResult;
+
+pub struct ComposerInput {
+    pub policy: PolicySnapshot,
+    pub ledger: VelocityLedgerSnapshot,
+    pub killswitch: KillSwitchSnapshot,
+    pub payer_atom: Option<AtomStatsView>,
+    pub payee_atom: Option<AtomStatsView>,
+    pub attestation: Option<ValidationAttestationView>,
+    pub amount: u64,
+    pub payee_agent_asset: Pubkey,
+    pub now_slot: u64,
+    pub unix_ts: i64,
+}
+
+pub struct ComposerResult {
+    pub decision: GateDecision,
+    pub spending_deltas: Option<SpendingDeltas>,
+    pub velocity_deltas: Option<VelocityDeltas>,
+}
+```
+
+The Anchor wrapper feeds the composer plain-data snapshots, never on-chain account references. That separation is what makes every policy unit-testable in plain Rust and Kani-provable without an Anchor harness.
+
+## Fail-fast order
+
+```
+KillSwitch  →  Spending  →  Velocity  →  CounterpartyTier  →  RequireValidation
+```
+
+Cheapest reads first. KillSwitch is one bool. Spending is pure arithmetic. Velocity reads one local PDA. CounterpartyTier reads two foreign `AtomStats` PDAs. RequireValidation reads one foreign `ValidationAttestation` PDA. The first policy that returns `Deny` short-circuits the rest — no foreign-PDA reads beyond the deciding policy.
+
+## State mutation rule
+
+The composer **never** mutates state. It returns *deltas* — `SpendingDeltas`, `VelocityDeltas` — that the Anchor handler applies to `PolicyAccount` and `VelocityLedger` only on the `Allow` branch.
+
+```rust
+match result.decision {
+    GateDecision::Allow => {
+        if let Some(d) = result.spending_deltas {
+            spending::apply_deltas(&mut ctx.accounts.policy_account, &d);
+        }
+        if let Some(d) = result.velocity_deltas {
+            velocity::apply_deltas(&mut ctx.accounts.velocity_ledger, &d);
+        }
+    }
+    GateDecision::Deny(_) | GateDecision::RequireValidation(_) => {
+        // Mutate nothing.
+    }
+}
+```
+
+This rule is what `velocity_counter_le_limit` (Kani #2) is inductive over: if the pre-state ledger satisfies `cumulative_amount ≤ max_in_window` and the policy returns `Allow(deltas)`, then the post-state ledger also satisfies the bound. A fresh ledger trivially satisfies the base case.
+
+## Strict variant
+
+`gate_payment_strict` converts non-`Allow` into `Err`:
+
+```rust
+pub fn gate_payment_strict(ctx: Context<GatePaymentStrict>, …) -> Result<()> {
+    let result = compose_decision(input);
+    match result.decision {
+        GateDecision::Allow => {
+            // Apply deltas, return Ok.
+            Ok(())
+        }
+        GateDecision::Deny(reason) => Err(reason.into()),
+        GateDecision::RequireValidation(_) => Err(ErrorCode::ValidationRequired.into()),
+    }
+}
+```
+
+The SDK's `composeAtomicSettleTx` calls `gate_payment_strict`. Any `Deny` on the gate fails the entire bundled transaction (`gate + transfer + emit_feedback`), which means the SPL transfer never runs and `FeedbackEmissionLog` is never created. Solana's transaction atomicity does the rest.
+
+The Phase J5 Kani proof `gate_payment_strict_correctness` pins this contract end-to-end:
+
+- `strict_returns_ok_iff_allow` — strict `Ok(())` ⇔ composer `Allow`.
+- `gate_decision_is_one_of_three_disjoint_variants` — the three `GateDecision` arms are pairwise disjoint, so a fourth variant cannot silently slip past the strict dispatch.
+
+Together: 258 sub-checks, ~0.9 s. The strict-correctness invariant is the on-chain anchor of the SDK's atomic-tx invariant.
+
+## Why pure-Rust
+
+Three reasons:
+
+1. **Kani provability.** `compose_decision` is a deterministic function over plain types. Kani's bounded model checker explores every reachable state inside the bounds in seconds. An Anchor handler with account validation, CPI, and rent calculations would not be tractable.
+2. **Unit-testability.** The same function works in `cargo test` without an Anchor program-test harness. Every policy module ships with a dense unit-test suite (Spending: 14 tests, Velocity: 14, CounterpartyTier: 13, RequireValidation: 13, KillSwitch: 2 — plus 113 module-level tests across PolicyVault).
+3. **Wrapper churn isolation.** Account-validation, IDL changes, Anchor-version bumps live in the wrapper. Decision logic doesn't move when wrappers do.
+
+## Read next
+
+<Cards>
+  <Card title="KillSwitch policy" href="/programs/policy-vault/kill-switch-policy">
+    First in the composer; one bool; multisig-gated mutation.
+  </Card>
+  <Card title="Spending policy" href="/programs/policy-vault/spending-policy">
+    Per-tx, daily (UTC), and weekly (ISO Monday) limits with anchor-rollover math.
+  </Card>
+  <Card title="Velocity policy" href="/programs/policy-vault/velocity-policy">
+    Sliding-window cumulative-spend counter with payer-tier-decayed window size.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    The strict variant is the on-chain half of the three-layer atomicity guard.
+  </Card>
+</Cards>

package/dist/embedded-docs/programs/policy-vault/counterparty-tier-policy.mdx

@@ -1,15 +1,87 @@
 ---
-title: Counterparty tier policy
-description: Quantu AtomStats trust-tier and risk checks used by the PolicyVault composer.
+title: CounterpartyTier policy
+description: Read Quantu's AtomStats by byte offset and gate the payment on tier, risk, and confidence — no Cargo dep on Quantu's crate.
 ---
 
-`In progress`
+CounterpartyTier is the wedge. It reads the payee's `AtomStats` PDA (Quantu's `atom-engine` program) through a manual byte-offset parser, then checks `trust_tier`, `risk_score`, and `confidence` against the policy's thresholds.
 
-The CounterpartyTier policy reads Quantu AtomStats fields through a manual byte parser, then checks trust tier, risk score, and confidence before payment release.
+Manual parsing — not Borsh deserialization through Quantu's crate. The parser is pinned to commit `bfb09ad` and includes a schema-version canary at byte 560 that fails loud rather than silently misreading fields if Quantu bumps its layout.
 
-| Source | Path |
-| --- | --- |
-| evaluator | [`programs/policy-vault/src/policies/counterparty_tier.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/counterparty_tier.rs) |
-| AtomStats parser | [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs) |
-| proof | [`programs/policy-vault/src/proofs/inv_counterparty_tier_monotone.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_counterparty_tier_monotone.rs) |
+Source: [`programs/policy-vault/src/policies/counterparty_tier.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/counterparty_tier.rs). Parser: [`programs/policy-vault/src/ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs).
 
+## Reads from `AtomStats`
+
+| Offset | Width | Field | Notes |
+|---:|---:|---|---|
+| `549` | u8 | `risk_score` | 0..=255 — lower is better |
+| `551` | u8 | `tier_immediate` | v1 demo default; 0..=4 |
+| `555` | u8 | `tier_confirmed` | post-vesting; production mode preferred |
+| `557` | u16 LE | `confidence` | basis points 0..=10000 |
+| `560` | u8 | `schema_version` | canary — must equal 1 |
+
+Account size canary: `ATOM_STATS_SIZE = 561`. Account-data-relative (the 8-byte Borsh discriminator at 0..8 is verified via owner + schema check, not by re-parsing).
+
+`ATOM_TIER_MAX = 4`. A tier byte above 4 — with `schema_version == 1` — implies tampering or an undeclared spec change; the parser fails with `AtomStatsSchemaMismatch` rather than silently clamp. Same fail-loud rule for `tier_confirmed`.
+
+Quantu pinned program ID (devnet): `AToMufS4QD6hEXvcvBDg9m1AHeCLpmZQsyfYa5h9MwAF`. Mainnet: [Reference → Mainnet program IDs](/reference/mainnet-program-ids).
+
+## Policy state (subset of `PolicyAccount`)
+
+```rust
+pub gate_mode: u8,                     // off 49      — GATE_MODE_IMMEDIATE | _CONFIRMED
+pub min_counterparty_tier: u8,         // off 130
+pub max_risk_score: u8,                // off 131     — 255 = no constraint
+pub min_confidence: u16,               // off 132..134 — 0..=10000; 0 = no constraint
+pub default_unrated_treatment: u8,     // off 134     — UNRATED_DENY | _ALLOW | _REQUIRE_VALIDATION
+```
+
+`gate_mode` selects which tier byte is checked. `GATE_MODE_IMMEDIATE` reads byte 551 (the v1 demo default — fast Quantu fast-path tier). `GATE_MODE_CONFIRMED` reads byte 555 (post-vesting; production policies prefer this). Any other byte falls back to `tier_confirmed` — the conservative choice if `gate_mode` is corrupted.
+
+## Decision
+
+```
+1. view = parse(atom_stats_account)
+2. view == None  → Unrated → composer applies default_unrated_treatment
+3. tier < min_tier              → Deny(CounterpartyTierBelowMin)        code 6
+4. max_risk_score < 255 AND view.risk_score > max_risk_score
+                                → Deny(CounterpartyRiskAboveMax)        code 7
+5. min_confidence > 0 AND view.confidence < min_confidence
+                                → Deny(CounterpartyConfidenceBelow)     code 8
+6. else                         → Allow
+```
+
+The risk constraint is disabled when `max_risk_score == 255` (sentinel). The confidence constraint is disabled when `min_confidence == 0`. Both let a policy elect tier-only gating without touching the other fields.
+
+## Unrated resolution
+
+When the payee's `AtomStats` PDA is uninitialised (no rent or empty data), the parser returns `None` and the policy returns `Unrated`. The composer maps `Unrated` to one of three resolutions per `default_unrated_treatment`:
+
+| Treatment | Constant | Composer maps to |
+|---|---|---|
+| `UNRATED_DENY` (default, byte `0`) | `0` | `Deny(UnratedTreatmentDeny)` — code 15 |
+| `UNRATED_ALLOW` | `1` | `Allow` — proceed |
+| `UNRATED_REQUIRE_VALIDATION` | `2` | `RequireValidation(capability_hash)` — facilitator routes user to attestation flow |
+
+Unrecognised bytes fall through to `Deny` — the safe landing if on-chain corruption ever yields a value outside the documented range.
+
+## Defensive failures (codes 9 / 10)
+
+The parser also surfaces two defensive denials independent of policy thresholds:
+
+- `AtomStatsWrongOwner` (code 9) — the PDA's owner is not Quantu's `atom-engine` program. Rejected via `require_keys_eq!` against the pinned `ATOM_ENGINE_ID`.
+- `AtomStatsSchemaMismatch` (code 10) — size mismatch (`!= 561`), schema-version canary mismatch (`byte 560 != 1`), or tier byte above `ATOM_TIER_MAX = 4`.
+
+Both are catastrophic-fail signals: a `Deny` here implies bad data, not a normal counterparty failure.
+
+## Formal verification
+
+- `counterparty_tier_monotone` (Kani #3, 8 sub-checks, 0.02 s) — if a STRICT policy (high `min_counterparty_tier`) produces `Allow` for a given payee, a LOOSER policy (lower or equal `min_tier`) on the same payee must also produce `Allow`. Loosening the tier requirement can never turn an `Allow` into a `Deny`.
+
+In-module tests cover gate-mode selection (immediate vs confirmed), risk + confidence boundaries, sentinel disabling, fail-fast ordering (tier before risk before confidence), and unrated resolution for all four `UNRATED_*` values including unknown.
+
+## Source
+
+- Policy module: [`policies/counterparty_tier.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/counterparty_tier.rs)
+- AtomStats parser: [`ext/atom_engine.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/atom_engine.rs)
+- Kani proof: [`proofs/inv_counterparty_tier_monotone.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_counterparty_tier_monotone.rs)
+- Byte-offset table: [Reference → Byte offsets](/reference/byte-offset-reference)