@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/verification/chained-validation.mdx

@@ -0,0 +1,87 @@
+---
+title: Chained validation
+description: The four-signature RequireValidation → respond → Allow trace that proves the third ERC-8004 leg actually closes the loop on Solana devnet.
+---
+
+Four signatures prove the third ERC-8004 leg closes the loop end to end. Subject = Quantu tier-3 agent the Pay.sh smoke also used; capability = `usdc-payment-policy.v1`; attestor identity reused from `examples/attestor-demo/attestor-keypair.json` (Phase D). Captured 2026-05-06.
+
+Source script: [`examples/attestor-demo/scripts/devnet-chained-validation.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/attestor-demo/scripts/devnet-chained-validation.ts). Trace JSON: [`examples/attestor-demo/devnet-chained-validation.json`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/attestor-demo/devnet-chained-validation.json).
+
+## The four signatures
+
+| Step | Decision | Tx |
+|---:|---|---|
+| 1 | `gate_payment` (no attestation account) → `RequireValidation` | [`3oKW7QugBLJ7kH2QbLLWEuEn3MyNmLWCj3XovCSdDQNmq5HriwNKvPMUR9TQByZPBAPbvprDfdeYDZvh7ofntRRh`](https://explorer.solana.com/tx/3oKW7QugBLJ7kH2QbLLWEuEn3MyNmLWCj3XovCSdDQNmq5HriwNKvPMUR9TQByZPBAPbvprDfdeYDZvh7ofntRRh?cluster=devnet) |
+| 2 | `request_validation` opens the request | [`2KbXYCF67D2f2fKHk5yTzrkFBr1mV47Q3Yb1veH5e3PX4PuLa66suodAUc7uTBnr6Y44NGV1TfHHMtAZiFSnbbRF`](https://explorer.solana.com/tx/2KbXYCF67D2f2fKHk5yTzrkFBr1mV47Q3Yb1veH5e3PX4PuLa66suodAUc7uTBnr6Y44NGV1TfHHMtAZiFSnbbRF?cluster=devnet) |
+| 3 | `respond_to_validation` (creates `ValidationAttestation` PDA `8YKq…xt2q`) | [`67CzMS9GEtUBesNznKpT2UWqvjEBzhgZd7AVkhXKQ5SoqRoBotcaYf1sTF8sHxj55TNT9k847nj7FQdrwAqKussp`](https://explorer.solana.com/tx/67CzMS9GEtUBesNznKpT2UWqvjEBzhgZd7AVkhXKQ5SoqRoBotcaYf1sTF8sHxj55TNT9k847nj7FQdrwAqKussp?cluster=devnet) |
+| 4 | `gate_payment` (with attestation) → `Allow` | [`dEXkCEeSn8uiVAa14u7EusdFufSuUQttmcTdLHMSq5J3VSARM4KMRCfwpRSkVmYBc1yRQuyvPMCebifCf1dmrmC`](https://explorer.solana.com/tx/dEXkCEeSn8uiVAa14u7EusdFufSuUQttmcTdLHMSq5J3VSARM4KMRCfwpRSkVmYBc1yRQuyvPMCebifCf1dmrmC?cluster=devnet) |
+
+## On-chain artefacts
+
+| Artefact | Address |
+|---|---|
+| Subject `agent_account` (Quantu tier-3 demo agent) | [`5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y`](https://explorer.solana.com/address/5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y?cluster=devnet) |
+| `CapabilityNamespace` for `usdc-payment-policy.v1` | [`34gonn86FjxzXZMGd43RSvQVyH1r6PrGV9xnHXjjkEwR`](https://explorer.solana.com/address/34gonn86FjxzXZMGd43RSvQVyH1r6PrGV9xnHXjjkEwR?cluster=devnet) |
+| Attestor's `AttestorProfile` | [`GTzWJzV5htNi1Ntqwq2e2ydu9h4rArnKQwzv2sJjC9zP`](https://explorer.solana.com/address/GTzWJzV5htNi1Ntqwq2e2ydu9h4rArnKQwzv2sJjC9zP?cluster=devnet) |
+| `ValidationRequest` (step 2's output) | [`GnbrSzWsDw1rehCrFJ4ckiM9JJJeAHdjfNDt7QQy7vhV`](https://explorer.solana.com/address/GnbrSzWsDw1rehCrFJ4ckiM9JJJeAHdjfNDt7QQy7vhV?cluster=devnet) |
+| `ValidationAttestation` (step 3's output — the headline read target) | [`C6Yr7oKcZ6sDVibR35SWbFnGCXyfQjLeRCiPbjxYq6vY`](https://explorer.solana.com/address/C6Yr7oKcZ6sDVibR35SWbFnGCXyfQjLeRCiPbjxYq6vY?cluster=devnet) |
+
+The `ValidationAttestation` PDA is what PolicyVault's `RequireValidation` policy reads at fixed byte offsets via [`policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs). After step 3 creates this PDA for `(subject, capability, attestor) = (5PfaofvE…, sha256(usdc-payment-policy.v1), GTzWJzV5…)`, a subsequent `gate_payment` call that passes this attestation account through the `validation_attestation` slot turns a `RequireValidation` decision into `Allow`.
+
+## What the trace proves
+
+1. **The third ERC-8004 leg is real on Solana.** Identity (Quantu) + Reputation (Quantu) + Validation (AgentTrust) all wire together.
+2. **The complete `RequireValidation` round-trip works.** PolicyVault emits `capabilityHash` → attestor responds → policy now allows. Each step is a separate on-chain tx; AgentTrust composes the PDAs without trusting any off-chain coordination.
+3. **The byte-offset parser reads the right fields.** PolicyVault's `RequireValidation` policy reads `subject_asset` at byte 8, `capability_hash` at byte 40, `attestor` at byte 72, `expires_at` at byte 208, `revoked` at byte 216 — exactly the offsets [`policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs) declares. The Phase F evidence reports verified each parsed value matches the on-chain raw bytes.
+4. **The Phase D demo capability hash is consistent end to end.** `sha256("usdc-payment-policy.v1") = a968ecd0b93d9bfe57aa62c56d1e439717cf51d1dfe0ec413267834f2ca08375` — the same digest that policy-vault's `required_capability_hash` stores, that `CapabilityNamespace` keys against, that `ValidationAttestation.capability_hash` carries.
+
+## Reproduce
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+
+pnpm --filter ./examples/attestor-demo run chained
+```
+
+Cost: ~0.012 SOL devnet total across the four txs. Output JSON: `examples/attestor-demo/devnet-chained-validation.json`.
+
+For the full lifecycle including revocation:
+
+```bash
+REVOKE=1 pnpm --filter ./examples/attestor-demo run chained
+```
+
+`REVOKE=1` runs the optional fifth step — `revoke_validation` sets `revoked=true` on the attestation PDA in place. A subsequent `gate_payment` call returns `Deny(AttestationRevoked)` (DenyReason code 13).
+
+## How a facilitator drives this in production
+
+The Pay.sh adapter ([`trustgate/server/src/facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh)) already surfaces `capabilityHash` in its `formatChallenge` response when the policy gate returns `RequireValidation`. A facilitator that hits this branch:
+
+1. Sees `decision.kind = "RequireValidation"` + `capabilityHash` in the x402 `/verify` response body (header `X-Capability-Required: <hex>`).
+2. Looks up the attestor service that handles that capability (typically discovered out-of-band via a registry or hard-coded contract).
+3. Submits the claim payload off chain; the attestor responds on chain via `respond_to_validation`.
+4. Re-submits the payment to the SERVICE; the new `/verify` call includes the `validation_attestation` PDA in the gate_payment account list, the policy reads it, and the decision flips to `Allow`.
+
+The script demonstrates steps 3-4 working end to end on devnet. Steps 1-2 are business logic the SERVICE owns. Walkthrough: [Custom attestor](/integration-guides/custom-attestor).
+
+## Validated by Kani
+
+- [`validation_expiry_correct`](/verification/kani-proofs#4-validation_expiry_correct) — an expired attestation cannot produce `Allow`.
+- [`gate_payment_strict_correctness`](/verification/kani-proofs#6-gate_payment_strict_correctness-phase-j5) — strict handler returns `Ok(())` if and only if the lazy composer returns `Allow`.
+
+If a future change broke the policy's expiry semantics or the `RequireValidation` arm slipped into `Ok`, both proofs fail loud. Plus the Anchor end-to-end suite covers the full lifecycle in [`tests/validation-registry.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/validation-registry.spec.ts).
+
+## Read next
+
+<Cards>
+  <Card title="Devnet smoke" href="/verification/devnet-smoke">
+    The Pay.sh + AT atomic-settlement trace.
+  </Card>
+  <Card title="Custom attestor" href="/integration-guides/custom-attestor">
+    Build the other side — register, respond, revoke.
+  </Card>
+  <Card title="Capability namespaces" href="/reference/capability-namespaces">
+    Every seeded v1 namespace with PDA + Explorer URL.
+  </Card>
+</Cards>

package/dist/embedded-docs/verification/devnet-smoke.mdx

@@ -0,0 +1,85 @@
+---
+title: Devnet smoke
+description: The Pay.sh + AgentTrust atomic-settlement trace on Solana devnet — gate, transfer, emit_feedback in one transaction. Reproducible from a clean checkout.
+---
+
+A real signed SPL transfer flowed through the demo's `/protected` endpoint, completed `gate_payment + transfer + emit_feedback` atomically, and wrote a `FeedbackEmissionLog` PDA on chain. Captured 2026-05-06.
+
+Source script: [`examples/pay-sh-demo/scripts/devnet-smoke.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/pay-sh-demo/scripts/devnet-smoke.ts). Trace JSON: [`examples/pay-sh-demo/devnet-smoke.json`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/pay-sh-demo/devnet-smoke.json).
+
+## The trace
+
+| Step | Tx |
+|---|---|
+| `emit_feedback` PDA-signed CPI → `agent_registry::give_feedback` → `atom_engine::update_stats` | [`jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) |
+| Signed SPL `transferChecked` (the proof Pay.sh's CLI would produce) | [`5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD`](https://explorer.solana.com/tx/5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD?cluster=devnet) |
+
+## On-chain artefacts
+
+| Artefact | Address | Notes |
+|---|---|---|
+| `FeedbackEmissionLog` PDA | [`HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) | Owned by trustgate · `score=100` · `is_dispute=0` · slot 460466788 |
+| Tier-3 `agent_account` | [`5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y`](https://explorer.solana.com/address/5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y?cluster=devnet) | Quantu's payee identity |
+| Tier-3 `atom_stats` | [`4z9RiK6B49QZbmqPM9yNZWgfxYD3tvQ3NETU6X89f5mv`](https://explorer.solana.com/address/4z9RiK6B49QZbmqPM9yNZWgfxYD3tvQ3NETU6X89f5mv?cluster=devnet) | `tier_immediate=3` after the feedback CPI |
+| Asset (Metaplex Core) | [`C6cuZeDT4kmCC1RXw8mzaoLGwmAMe5fHDvutAjicVi8B`](https://explorer.solana.com/address/C6cuZeDT4kmCC1RXw8mzaoLGwmAMe5fHDvutAjicVi8B?cluster=devnet) | Quantu MPL-Core asset |
+| Facilitator authority PDA | [`4TWqmxoMQRSJTmH879TDWqvqgiEwr9akWnpPVg51Z5Bg`](https://explorer.solana.com/address/4TWqmxoMQRSJTmH879TDWqvqgiEwr9akWnpPVg51Z5Bg?cluster=devnet) | TrustGate's PDA-signer for the CPI |
+
+## What the trace proves
+
+1. **All three Anchor programs are executable on devnet.** PolicyVault, TrustGate, and (transitively, since `atom_stats` exists for the demo agent) the Quantu agent-registry are reachable from off-chain code.
+2. **The PDA-signed CPI works.** TrustGate's `["trustgate_auth", facilitator]` PDA signed a CPI into Quantu's `give_feedback`. The resulting `atom_stats` was bumped — Quantu's reputation surface accepted the feedback.
+3. **Idempotency holds.** The `FeedbackEmissionLog` exists on chain at the predicted PDA seeds `["feedback_log", payment_id_hash]`. A second `emit_feedback` for the same `payment_id_hash` would fail account-already-in-use; retries cannot double-emit.
+4. **The atomic-tx invariant is enforced end to end on devnet.** The SDK's `composeAtomicSettleTx` produces one `Transaction` with three instructions in canonical order; both the gate-mutation and the feedback-emission committed in the same slot.
+
+## Reproduce
+
+From a clean checkout:
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+
+# 1. publish IDLs (one-time, ~0.03 SOL)
+anchor idl init --provider.cluster devnet \
+  --filepath target/idl/trustgate.json HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N
+anchor idl init --provider.cluster devnet \
+  --filepath target/idl/policy_vault.json 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR
+anchor idl init --provider.cluster devnet \
+  --filepath target/idl/validation_registry.json Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv
+
+# 2. pre-warm 3 Quantu agents (one-time, ~0.04 SOL)
+pnpm --filter ./examples/pay-sh-demo exec ts-node scripts/prewarm-devnet.ts
+
+# 3. run the smoke (~0.03 SOL)
+pnpm --filter ./examples/pay-sh-demo exec ts-node scripts/devnet-smoke.ts
+```
+
+The full trace (signatures, PDAs, slot numbers) lands in `examples/pay-sh-demo/devnet-smoke.json`. Re-running is idempotent — `TrustGateAuthority`, test mint, payer keypair, and ATAs are reused if present.
+
+## Daily smoke (cron)
+
+[`.github/workflows/daily-devnet-smoke.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/daily-devnet-smoke.yml) runs the same flow on a 24-hour cron. The result is committed back to the repo at [`docs/proofs/smoke-2026-05-06.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/smoke-2026-05-06.md) (template). A failed daily smoke flips a status badge red; a green smoke means devnet, the Quantu programs, and AgentTrust's three programs are all healthy.
+
+## Anchor end-to-end suite
+
+The Anchor TS suite at [`tests/`](https://github.com/agenttrust-labs/agenttrust/tree/main/tests) covers 50 end-to-end cases including the atomic-tx invariant, chained kill-switch atomicity, and full RequireValidation lifecycle. Run via:
+
+```bash
+anchor test --skip-deploy --provider.cluster devnet
+```
+
+Adversarial-harness coverage: [Adversarial harness](/verification/adversarial-harness).
+
+## Read next
+
+<Cards>
+  <Card title="Chained validation" href="/verification/chained-validation">
+    Four-signature trace through the third ERC-8004 leg.
+  </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="Live evidence" href="/verification/live-evidence">
+    Consolidated index across every claim.
+  </Card>
+</Cards>

package/dist/embedded-docs/verification/index.mdx

@@ -0,0 +1,31 @@
+---
+title: Verification
+description: Every load-bearing claim in AgentTrust has an independently checkable artifact — a Kani proof, a devnet tx signature, a localnet test, a cron job. This section indexes them.
+---
+
+If you're a judge with five minutes, start with [Live evidence](/verification/live-evidence) — every claim with a clickable Explorer URL.
+
+If you're a developer debugging a specific property, jump straight to the relevant per-claim page below.
+
+## Pages
+
+<Cards>
+  <Card title="Live evidence" href="/verification/live-evidence">
+    Consolidated index — Kani 6/6 + 635 sub-checks, devnet smoke, chained validation, capability namespaces, daily-smoke cron. Every claim with an Explorer URL.
+  </Card>
+  <Card title="Kani proofs" href="/verification/kani-proofs">
+    Six machine-checked invariants over the pure-Rust composer. Per-harness deep-dive: file path, sub-check count, time, what it proves, what it doesn't.
+  </Card>
+  <Card title="Devnet smoke" href="/verification/devnet-smoke">
+    The Pay.sh + AgentTrust atomic-settlement trace on Solana devnet — gate, transfer, emit_feedback CPI, all in one tx, with reproduction commands.
+  </Card>
+  <Card title="Chained validation" href="/verification/chained-validation">
+    The four-signature RequireValidation → respond → Allow trace that proves the third ERC-8004 leg actually closes the loop.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Three layers of proof — compile-time literal-type guard, runtime throw, composer structure — plus the on-chain Kani strict-correctness binding.
+  </Card>
+  <Card title="Adversarial harness" href="/verification/adversarial-harness">
+    Fourteen hostile-scenario assertions in tests/adversarial.spec.ts that exercise the gate against malformed PDAs, replayed proofs, and corrupted state.
+  </Card>
+</Cards>

package/dist/embedded-docs/verification/kani-proofs.mdx

@@ -0,0 +1,144 @@
+---
+title: Kani proofs
+description: Six machine-checked invariants over the pure-Rust composer — 635 sub-checks, zero failures, ~80 s on a single CI runner. Per-harness deep-dive.
+---
+
+PolicyVault ships with six `#[kani::proof]` harnesses over the pure-Rust composer (and one helper). Each runs on every PR via [`.github/workflows/kani-prove.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/kani-prove.yml). Source: [`programs/policy-vault/src/proofs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/policy-vault/src/proofs).
+
+Kani is the [model-checking/kani](https://github.com/model-checking/kani) bounded model checker. It compiles the Rust under verification to CBMC's intermediate form and explores every reachable state inside the configured bounds.
+
+<KaniProofBadge />
+
+## Six invariants — summary
+
+| # | Invariant | Sub-checks | Time | Bound |
+|---:|---|---:|---:|---|
+| 1 | `paused_implies_no_allow` | 126 | 0.25 s | `#[kani::unwind(N)]` on the policy-bitmask scan |
+| 2 | `velocity_counter_le_limit` | 9 | 0.03 s | none |
+| 3 | `counterparty_tier_monotone` | 8 | 0.02 s | none |
+| 4 | `validation_expiry_correct` | 85 | 0.23 s | none |
+| 5 | `multisig_threshold_enforced` | 149 | 77.17 s | 3 members + 3 signers |
+| 6 | `gate_payment_strict_correctness` | 258 | ~0.9 s | none |
+
+**Total: 635 sub-checks, 0 failures, ~80 s.** Phase J5 added invariant 6.
+
+## 1 · `paused_implies_no_allow`
+
+**Property.** If the agent's KillSwitch is `paused == true` AND `KIND_KILLSWITCH` is set in the policy bitmask, `compose_decision` cannot return `Allow` for any values of the other policy fields, ledger, or input parameters.
+
+**File.** [`proofs/inv_paused_implies_no_allow.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_paused_implies_no_allow.rs). **Harness:** `paused_killswitch_implies_no_allow`.
+
+**Why it's load-bearing.** This is the safety invariant of the gate. If a future change re-orders or skips KillSwitch evaluation, Kani fails this proof loud.
+
+## 2 · `velocity_counter_le_limit`
+
+**Property.** Inductive form: if the pre-state ledger satisfies `cumulative_amount ≤ max_in_window`, then after `velocity::evaluate` returns `Allow(deltas)` the new cumulative counter still satisfies the bound.
+
+**File.** [`proofs/inv_velocity_counter_le_limit.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_velocity_counter_le_limit.rs). **Harness:** `velocity_allow_implies_cumulative_le_max`.
+
+**Why it's inductive.** Every prior `Allow` preserves the bound; a fresh ledger trivially satisfies the base case. Cross-policy preservation against `spending.weekly_max` is a separate proof if/when needed.
+
+The `apply_deltas` rule on the composer side — only on `Allow` — is what makes this inductive on chain. If a future change applied deltas on `Deny` or `RequireValidation`, this proof becomes a falsehood.
+
+## 3 · `counterparty_tier_monotone`
+
+**Property.** 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`.
+
+**File.** [`proofs/inv_counterparty_tier_monotone.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_counterparty_tier_monotone.rs). **Harness:** `counterparty_tier_monotone`.
+
+**Why it's anti-regression.** This is a sanity invariant. If a refactor introduces non-monotone behaviour (e.g., a config combination where loosening the threshold accidentally tightens it), Kani fails.
+
+## 4 · `validation_expiry_correct`
+
+**Property.** An expired attestation (`expires_at != 0 AND expires_at <= now_slot`) cannot produce `Allow` from `require_validation::evaluate`.
+
+**File.** [`proofs/inv_validation_expiry_correct.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_validation_expiry_correct.rs). **Harness:** `validation_expiry_correct`.
+
+**Why it matters.** Subject + capability + revocation are forced equal in the symbolic search so expiry is the deciding gate. Closes the obvious time-of-check / time-of-use stale-attestation hole — even if a payment race somehow passes a stale attestation through the verify path, the expiry check on the gate itself denies it.
+
+## 5 · `multisig_threshold_enforced`
+
+**Property.** `PolicyAuthority::count_distinct_signing_members` cannot return a count exceeding `min(member_count, signer_keys.len())`.
+
+**File.** [`proofs/inv_multisig_threshold_enforced.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_multisig_threshold_enforced.rs). **Harness:** `multisig_threshold_enforced`.
+
+**Why it's load-bearing.** This is the property that backs `set_killswitch`'s `require!(distinct_count >= threshold)` gate. A caller cannot construct a signer set that fools the function into over-counting (duplicate pubkeys, off-by-one tricks, corrupted `members` arrays).
+
+**Bound.** 3 members + 3 signers for symbolic-search tractability; the property generalises by induction.
+
+## 6 · `gate_payment_strict_correctness` (Phase J5)
+
+**Property.** Two harnesses pin the SDK's atomicity contract end-to-end:
+
+- `strict_returns_ok_iff_allow` — `compose_decision == Allow` ⇒ strict handler returns `Ok(())`. `compose_decision == Deny(_)` ⇒ strict returns `Err(_)`. `compose_decision == RequireValidation` ⇒ strict returns `Err(_)`.
+- `gate_decision_is_one_of_three_disjoint_variants` — the three `GateDecision` arms are pairwise disjoint, so a future fourth variant cannot silently slip past the strict dispatch.
+
+Together: `strict_returns_ok ⇔ matches!(decision, Allow)`.
+
+**File.** [`proofs/inv_gate_payment_strict_correctness.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_gate_payment_strict_correctness.rs).
+
+**Why it matters.** This is the on-chain anchor of the SDK's atomic-tx invariant. The SDK enforces atomicity at three TS layers; this proof pins the on-chain handler that those layers feed into. If a future change re-routes the `Deny` arm to an `Ok` return, both the TS guards and this proof fail loud.
+
+Sub-check breakdown:
+
+| Sub-harness | Failed | Sub-checks | Unreachable |
+|---|---:|---:|---:|
+| `strict_returns_ok_iff_allow` | 0 | 131 | 3 |
+| `gate_decision_is_one_of_three_disjoint_variants` | 0 | 127 | 3 |
+
+Combined: 0 / 258 failed.
+
+## Reproduce locally
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+cargo install --locked kani-verifier
+cargo kani setup
+
+cd programs/policy-vault
+
+cargo kani --harness paused_killswitch_implies_no_allow
+cargo kani --harness velocity_allow_implies_cumulative_le_max
+cargo kani --harness counterparty_tier_monotone
+cargo kani --harness validation_expiry_correct
+cargo kani --harness multisig_threshold_enforced
+cargo kani --harness strict_returns_ok_iff_allow
+cargo kani --harness gate_decision_is_one_of_three_disjoint_variants
+```
+
+Or run all six via the CI workflow:
+
+```bash
+gh workflow run kani-prove.yml
+```
+
+Expected output per harness:
+
+```
+SUMMARY:
+ ** 0 of <N> failed (<X> unreachable)
+
+VERIFICATION:- SUCCESSFUL
+```
+
+## What Kani does NOT prove
+
+- **Anchor handler account validation.** These are tested via [`tests/policy-vault.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/policy-vault.spec.ts) — Anchor end-to-end suite, 50 cases.
+- **Borsh deserialization correctness of foreign PDAs.** Manual byte-offset parsers in [`programs/policy-vault/src/ext/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/policy-vault/src/ext); unit tests + runtime constraint checks per parser.
+- **Integer overflow in the SPL token transfer.** Legacy SPL token's own invariant — out of scope for AgentTrust verification.
+- **Liveness.** A denied request never reaches Allow, but the proofs do not bound the number of denials before an Allow eventually fires. Liveness + economic-game-theoretic properties are out of scope for v1.
+
+The six invariants above are the **safety** properties: nothing catastrophic happens.
+
+## Why bounded
+
+Kani is a bounded model checker. Two of the proofs (`paused_implies_no_allow`, `multisig_threshold_enforced`) use `#[kani::unwind(N)]` to cap loop iterations. This is the standard discipline for finite-state proofs over Solana data — member arrays cap at 7 per `PolicyAuthority`, atom-engine tier domain is `0..=4`, etc. The bounds match production-realistic state sizes; symbolic search exhausts all reachable states inside those bounds.
+
+For an unbounded inductive proof on top of these, the canonical next step is `qedgen-formal-verification` (Lean 4 + Kani harness compilation from a single `.qedspec`), tracked as a v1.1 hardening item.
+
+## Source
+
+- All proofs: [`programs/policy-vault/src/proofs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/policy-vault/src/proofs)
+- Workflow: [`.github/workflows/kani-prove.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/kani-prove.yml)
+- README: [`docs/proofs/README.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/README.md)
+- Sub-check summary: [`docs/proofs/kani-summary.txt`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/kani-summary.txt)

package/dist/embedded-docs/verification/live-evidence.mdx

@@ -0,0 +1,180 @@
+---
+title: Live evidence
+description: Every AgentTrust claim with an independently checkable artifact — Kani proofs, devnet tx signatures, localnet tests, cron jobs, hosted endpoints. One page.
+---
+
+Every claim on this page is checkable from a terminal in under five minutes. No login. No clone (unless you want to re-run the proofs locally). Each row links to the artifact directly.
+
+Captured 2026-05-08 against `main` post-Phase Q1.
+
+## Three programs deployed on devnet
+
+| Program | Address | Explorer | IDL |
+|---|---|---|---|
+| `policy_vault` | `8Y6f…QTR` | [Open](https://explorer.solana.com/address/8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR?cluster=devnet) | published |
+| `trustgate` | `HF8z…ih2N` | [Open](https://explorer.solana.com/address/HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N?cluster=devnet) | published |
+| `validation_registry` | `Cx4R…Khtv` | [Open](https://explorer.solana.com/address/Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv?cluster=devnet) | published |
+
+Verify executable status:
+
+```bash
+for p in 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR \
+         HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N \
+         Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv; do
+  solana program show "$p" --url devnet | grep Executable
+done
+```
+
+## Six Kani proofs
+
+<KaniProofBadge />
+
+| # | Invariant | Sub-checks | Time |
+|---:|---|---:|---:|
+| 1 | `paused_implies_no_allow` | 126 | 0.25 s |
+| 2 | `velocity_counter_le_limit` | 9 | 0.03 s |
+| 3 | `counterparty_tier_monotone` | 8 | 0.02 s |
+| 4 | `validation_expiry_correct` | 85 | 0.23 s |
+| 5 | `multisig_threshold_enforced` | 149 | 77.17 s |
+| 6 | `gate_payment_strict_correctness` (J5) | 258 (`131 + 127`) | ~0.9 s |
+
+**Total: 635 sub-checks, 6/6 proven, ~80 s on a single CI runner.** Workflow: [`.github/workflows/kani-prove.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/kani-prove.yml). Per-harness deep-dive: [Kani proofs](/verification/kani-proofs).
+
+Reproduce:
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+cargo install --locked kani-verifier
+cargo kani --manifest-path programs/policy-vault/Cargo.toml \
+  --harness paused_killswitch_implies_no_allow
+```
+
+## Pay.sh + AgentTrust atomic settlement (live devnet)
+
+A real signed SPL transfer flowed through `demo.agenttrust.tech/protected`, completed `gate_payment + transfer + emit_feedback` atomically, and wrote a `FeedbackEmissionLog` PDA on chain (2026-05-06).
+
+| Step | Tx |
+|---|---|
+| `emit_feedback` PDA-signed CPI → Quantu `give_feedback` → `update_stats` | [`jMobmWJUAXuL8…`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) |
+| signed SPL `transferChecked` (the proof Pay.sh's CLI would produce) | [`5iV8EYmJh9XS…`](https://explorer.solana.com/tx/5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD?cluster=devnet) |
+
+Resulting on-chain artefacts:
+
+| Artefact | Address |
+|---|---|
+| `FeedbackEmissionLog` PDA (owned by trustgate, score=100, slot 460466788) | [`HB4BBi9j…`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) |
+| Tier-3 `agent_account` | [`5Pfa…K8y`](https://explorer.solana.com/address/5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y?cluster=devnet) |
+| Tier-3 `atom_stats` | [`4z9R…f5mv`](https://explorer.solana.com/address/4z9RiK6B49QZbmqPM9yNZWgfxYD3tvQ3NETU6X89f5mv?cluster=devnet) |
+| Asset (Metaplex Core) | [`C6cu…Vi8B`](https://explorer.solana.com/address/C6cuZeDT4kmCC1RXw8mzaoLGwmAMe5fHDvutAjicVi8B?cluster=devnet) |
+| Facilitator authority PDA | [`4TWq…Z5Bg`](https://explorer.solana.com/address/4TWqmxoMQRSJTmH879TDWqvqgiEwr9akWnpPVg51Z5Bg?cluster=devnet) |
+
+Reproduce: see [Devnet smoke](/verification/devnet-smoke).
+
+## Chained validation — third ERC-8004 leg, full lifecycle (live devnet)
+
+Four signatures prove the third leg actually closes the loop. Subject = the same Quantu tier-3 agent the Pay.sh trace used; capability = `usdc-payment-policy.v1` (2026-05-06).
+
+| 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 PDA `8YKq…xt2q`) | [`67CzMS9GEt…`](https://explorer.solana.com/tx/67CzMS9GEtUBesNznKpT2UWqvjEBzhgZd7AVkhXKQ5SoqRoBotcaYf1sTF8sHxj55TNT9k847nj7FQdrwAqKussp?cluster=devnet) |
+| `gate_payment` (with attestation) → `Allow` | [`dEXkCEeSn8…`](https://explorer.solana.com/tx/dEXkCEeSn8uiVAa14u7EusdFufSuUQttmcTdLHMSq5J3VSARM4KMRCfwpRSkVmYBc1yRQuyvPMCebifCf1dmrmC?cluster=devnet) |
+
+`ValidationAttestation` PDA: [`8YKq…xt2q`](https://explorer.solana.com/address/8YKqxoBaKfQ4VcDNa6dcoMQGevxbRmcr4ENbWcyrJxt2q?cluster=devnet). Reproduce + full trace: [Chained validation](/verification/chained-validation).
+
+## Ten capability namespaces seeded (live devnet)
+
+Every PDA exists on chain. Auto-generated lookup with per-namespace Explorer URLs: [Reference → Capability namespaces](/reference/capability-namespaces). Every name decomposes to `MAX_NAME_LEN = 32` per the on-chain bound; the playbook-level descriptive labels live in the schema-URI document.
+
+Reproduce: `pnpm --filter ./examples/attestor-demo run seed:namespaces` is idempotent.
+
+## Hosted services (Fly.io)
+
+| Service | URL | Healthz |
+|---|---|---|
+| Demo | [`demo.agenttrust.tech`](https://demo.agenttrust.tech) | `GET /health` |
+| Facilitator (`/verify` + `/settle`) | [`api.agenttrust.tech`](https://api.agenttrust.tech) | `GET /healthz` |
+| MCP HTTP endpoint | [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) | `GET /healthz` (returns `version: "0.2.6"`, `toolCount: 18`) |
+
+Singapore region, `shared-cpu-1x@256MB`, two machines for HA, `min_machines_running = 1`. Lets-Encrypt certs on every subdomain.
+
+## Atomic-tx invariant — three layers + on-chain anchor
+
+| Layer | What it proves | Evidence |
+|---|---|---|
+| Compile-time literal-type guard | `AtomicityEnforced` is `{ atomicityEnforced: true }` (literal `true`). TS rejects `false`, missing, or `boolean` widening. | [`trustgate/sdk/src/atomicity.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/atomicity.ts) lines 31-33 |
+| Runtime guard | `assertAtomicityEnforced` throws `AtomicityNotEnforcedError` for any value that isn't strictly `=== true`. Catches `as any` casts. | [`trustgate/sdk/src/atomicity.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/atomicity.ts) lines 51-58 |
+| Composer structure | `composeAtomicSettleTx` returns one `Transaction` with exactly three instructions in canonical order. | [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) `describe("composeAtomicSettleTx")` (5 cases) |
+| Single-tx atomic revert (localnet) | Bundled tx with failing inner ix reverts the whole bundle; `gate_payment_strict` rolls back. | [`tests/atomic-tx-invariant.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/atomic-tx-invariant.spec.ts) `describe("B. single-tx atomic revert")` |
+| Split-tx corruption (localnet) | Splitting the bundle leaves `VelocityLedger` dirty after the transfer reverts — the fault model A+B prevents. | [`tests/atomic-tx-invariant.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/atomic-tx-invariant.spec.ts) `describe("C. split-tx anti-pattern corrupts state")` |
+| On-chain anchor | `gate_payment_strict_correctness` Kani proof binds strict `Ok(())` to composer `Allow`. | [`programs/policy-vault/src/proofs/inv_gate_payment_strict_correctness.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_gate_payment_strict_correctness.rs) |
+
+Full deep-dive: [Atomic-tx invariant](/verification/atomic-tx-invariant). Background writeup: [`docs/proofs/transfer-hook-atomicity.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/transfer-hook-atomicity.md).
+
+## Adversarial harness — fourteen hostile-scenario assertions
+
+[`tests/adversarial.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/adversarial.spec.ts) exercises the gate against malformed PDAs, replayed proofs, corrupted state, schema-version drift, expired attestations, off-curve attestor pubkeys, and more. Per-scenario detail: [Adversarial harness](/verification/adversarial-harness).
+
+## Test coverage
+
+| Layer | Count | Where |
+|---|---:|---|
+| Rust unit tests | 113 | `cargo test --workspace --lib` |
+| Kani formal proofs | 6 / 635 sub-checks | `cargo kani` per proof harness |
+| Anchor TS end-to-end | 50 | `anchor test --provider.cluster devnet` |
+| Adversarial harness | 14 | `tests/adversarial.spec.ts` |
+| SDK unit tests | 56 (+ 16 INTEGRATION-gated) | `cd trustgate/sdk && pnpm test` |
+| Server adapter tests | 146 | `cd trustgate/server && pnpm test` |
+| MCP unit tests | 76 (+ 3 INTEGRATION + 21 protocol-conformance) | `cd mcp && pnpm test` |
+| pay-sh-demo flow | 7 (+ 1 INTEGRATION) | `cd examples/pay-sh-demo && pnpm test` |
+| attestor-demo lifecycle | 6 (INTEGRATION-gated) | `cd examples/attestor-demo && pnpm test` |
+| **Total** | **~360 tests + 6 formal proofs + 14 adversarial scenarios** | All green on `main` |
+
+## CI workflows (15 total)
+
+| Workflow | Purpose |
+|---|---|
+| `kani-prove.yml` | All 6 Kani proofs on every PR |
+| `kani-budget.yml` | Total runtime ceiling for Kani |
+| `anchor-test.yml` | Full Anchor end-to-end with Quantu mainnet clones |
+| `ts-test.yml` | SDK + server + web + demo + MCP build/test |
+| `adapter-contract-conformance.yml` | Adapter-contract walk |
+| `mcp-protocol-conformance.yml` | 21 MCP protocol assertions |
+| `bundle-size.yml` | SDK npm pack-size budget |
+| `daily-devnet-smoke.yml` | Cron — full devnet round-trip every 24h |
+| `devnet-integration.yml` | Gated on `DEVNET_FACILITATOR_KEYPAIR` secret |
+| `idl-diff.yml` | ABI-stability gate vs deployed IDL |
+| `link-check.yml` | README + MDX dead-link sweep |
+| `lint-and-format.yml` | tsc + cargo fmt + clippy |
+| `lockfile-freshness.yml` | pnpm + Cargo.lock drift |
+| `secret-scan.yml` | gitleaks against the diff |
+| `build.yml` | cargo + anchor build |
+
+Latest run summary: [`docs/proofs/ci-runs.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/ci-runs.md).
+
+## Phase reports
+
+| Phase | Date | Report |
+|---|---|---|
+| F (verification) | 2026-05-06 | [`phase-f-verification-report.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-f-verification-report.md) |
+| G | 2026-05-07 | [`phase-g-report.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-g-report.md) |
+| H (hosting + npm) | 2026-05-07 | [`phase-h-report.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-h-report.md) |
+| J (Kani strict-correctness) | 2026-05-07 | [`phase-j-report.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-j-report.md) |
+| M (MCP comprehensive E2E) | 2026-05-07 | [`phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) |
+| P (real-LLM tool routing) | 2026-05-08 | [`phase-p-llm-routing.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-p-llm-routing.md) |
+| Atomic-tx invariant proof | 2026-05-07 | [`transfer-hook-atomicity.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/transfer-hook-atomicity.md) |
+
+## Read next
+
+<Cards>
+  <Card title="Kani proofs" href="/verification/kani-proofs">
+    Per-harness deep-dive — what each proof binds and what it doesn't.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Three SDK layers + the on-chain Kani anchor.
+  </Card>
+  <Card title="Devnet smoke" href="/verification/devnet-smoke">
+    The Pay.sh + AT atomic-settlement trace, expanded with reproduction commands.
+  </Card>
+</Cards>

package/dist/tools/read/get-quantu-reputation.d.ts

@@ -1,12 +1,27 @@
 /**
  * `agenttrust_get_quantu_reputation` — read the Quantu atom_stats PDA
- * for an agent and surface the on-chain reputation tier + counts.
+ * for an agent and surface the on-chain reputation tier + risk fields.
  *
  * Quantu's atom_stats account isn't in our IDL — we fetch raw account
- * bytes and decode the byte-offset surface PolicyVault's AtomStats
- * parser uses (`programs/policy-vault/src/ext/atom_stats.rs`). The
- * exact offsets are pinned there; this tool mirrors them so what the
- * gate sees is what the tool reports.
+ * bytes and decode the byte-offset surface PolicyVault's CounterpartyTier
+ * policy reads at gate time. Source-of-truth offsets live in
+ * `programs/policy-vault/src/ext/atom_engine.rs:21-27` and are mirrored
+ * verbatim here. If Quantu changes the layout the schema-version canary
+ * at byte 560 catches it and the tool returns a clean error rather than
+ * bogus values.
+ *
+ * Tier semantics:
+ *
+ *   - `tierImmediate` is the v1 fast-path tier — settled within the
+ *     same `give_feedback` tx that bumped the score. Used by the
+ *     CounterpartyTier policy in v1 demo mode.
+ *   - `tierConfirmed` is the post-vesting tier — only counted once the
+ *     vesting window elapses. Production-mode policies prefer this.
+ *
+ * Phase P found the previous implementation read fabricated offsets
+ * (40 / 41 / 49 / 50 / 51 instead of 549 / 551 / 555 / 557) which
+ * returned `tier: 164` for an actually-tier-0 agent. 0.2.6 corrects
+ * this and adds the schema-version canary the on-chain parser uses.
  */
 import { z } from "zod";
 import type { Tool } from "../types";
@@ -26,14 +41,38 @@ interface Output {
     ownerProgram: string | null;
     ownerExpected: string;
     ownerMatches: boolean;
+    rawByteLen: number;
+    /** Set when the schema-version canary fails or the account is undersized. */
+    error?: string;
     reputation?: {
-        tier: number;
-        feedbackCount: string;
-        averageScore: number | null;
-        riskScore: number | null;
-        confidence: number | null;
+        /** v1 fast-path tier (0..=4). The CounterpartyTier policy reads
+         *  this in v1 demo mode. */
+        tierImmediate: number;
+        /** Post-vesting confirmed tier (0..=4). Production policies prefer
+         *  this once vesting windows are configured. */
+        tierConfirmed: number;
+        /** 0..=255 — lower is better. */
+        riskScore: number;
+        /** Confidence in the reputation reading, basis points (0..=10_000)
+         *  per Quantu's atom_engine spec; carried as a u16 here. */
+        confidence: number;
+        /** Schema version (always 1 in v1 — checked as a canary). */
+        schemaVersion: number;
     };
-    rawByteLen: number;
 }
+export declare const ATOM_STATS_SIZE = 561;
+export declare const ATOM_STATS_RISK_SCORE_OFFSET = 549;
+export declare const ATOM_STATS_TIER_IMMEDIATE_OFFSET = 551;
+export declare const ATOM_STATS_TIER_CONFIRMED_OFFSET = 555;
+export declare const ATOM_STATS_CONFIDENCE_OFFSET = 557;
+export declare const ATOM_STATS_SCHEMA_VERSION_OFFSET = 560;
+export declare const ATOM_STATS_SCHEMA_VERSION_EXPECTED = 1;
+export declare const ATOM_TIER_MAX = 4;
+/** Pure-fn bytes → reputation. Returns `{ error }` when the buffer fails any
+ *  canary (size, schema_version, tier-range). Mirrors the on-chain parser's
+ *  fail-loud semantics — caller surfaces the error. */
+export declare function decodeAtomStatsBytes(data: Buffer | Uint8Array): NonNullable<Output["reputation"]> | {
+    error: string;
+};
 export declare const getQuantuReputationTool: Tool<Input, Output>;
 export {};