@agenttrust-sdk/mcp 0.2.6 → 0.3.0

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

@@ -1,73 +1,174 @@
 ---
 title: "@agenttrust-sdk/trustgate"
-description: TypeScript client helpers, Express middleware, and atomicity guard.
+description: TypeScript surface for AgentTrust on Solana — Express middleware, client helpers, atomicity guard, PDA derivers, and the full ValidationRegistry instruction builder set.
 ---
 
-The SDK is the facilitator-facing TypeScript package. The server adapter layer currently carries the concrete Pay.sh integration and the demo path; the package API remains the smaller client / Express surface for apps that call AgentTrust directly.
+[`@agenttrust-sdk/trustgate@0.2.0`](https://www.npmjs.com/package/@agenttrust-sdk/trustgate) is the TypeScript package every facilitator pulls in. Express middleware, client helpers for direct calls, the atomicity guard, PDA derivers + Anchor loaders for all three programs, and instruction builders for ValidationRegistry's full lifecycle.
+
+Source: [`trustgate/sdk/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/sdk). License: MIT.
+
+## Install
 
 ```bash
 pnpm add @agenttrust-sdk/trustgate
+# or: npm install @agenttrust-sdk/trustgate
+# or: yarn add @agenttrust-sdk/trustgate
 ```
 
-## Imports
+Peer dep: `express ^4.21` (only required if you mount the middleware). Node `>=20`.
+
+## Three import surfaces
 
 ```ts
-import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
-import { gatePayment, settle, dispute } from "@agenttrust-sdk/trustgate/client";
-import {
-  AtomicityNotEnforcedError,
-  DEFAULT_DEVNET_PROGRAM_IDS,
-  derivePolicyPda,
-} from "@agenttrust-sdk/trustgate";
+import { mountTrustGate }                   from "@agenttrust-sdk/trustgate/express";
+import { gatePayment, settle, dispute }     from "@agenttrust-sdk/trustgate/client";
+import { composeAtomicSettleTx }            from "@agenttrust-sdk/trustgate";
 ```
 
-## gatePayment
+The root namespace re-exports every helper grouped by concern — atomicity guard, PDA derivers, Anchor loaders, Quantu helpers, ValidationRegistry instruction builders, SPL helpers, x402 header constants. Full list: [Exports reference](/sdk/exports-reference).
+
+The `/express` and `/client` subpaths are tree-shake-friendly entry points; the root namespace doesn't re-export them so a client-only consumer doesn't pull Express into the bundle.
 
-`gatePayment()` is a read-only decision call.
+## Quick start — Express
 
 ```ts
-type GateDecision =
-  | { kind: "Allow" }
-  | { kind: "Deny"; reasonCode: number; reasonName: string }
-  | { kind: "RequireValidation"; capabilityHash: number[] };
+import express from "express";
+import { Keypair } from "@solana/web3.js";
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+
+const app = express();
+app.use(express.json());
+
+await mountTrustGate(app, {
+  rpcUrl:             "https://api.devnet.solana.com",
+  facilitatorKeypair: Keypair.fromSecretKey(/* facilitator key */),
+  network:            "solana-devnet",
+  atomicityEnforced:  true,                // literal `true`
+});
+
+app.listen(3000);
 ```
 
-The helper simulates the Anchor instruction and parses the return-data channel into the TypeScript union.
+Mounts four routes:
+
+| Route | Purpose |
+|---|---|
+| `POST /verify` | Read-only `gate_payment` simulation. Returns 200/Allow, 402/Deny + reason headers, or 402/RequireValidation + capability hash. |
+| `GET /receipt/:paymentIdHashHex` | `FeedbackEmissionLog` lookup. Returns `{ exists: false }` until settlement. |
+| `POST /settle` | Atomic settle (`gate_payment_strict + transferChecked + emit_feedback`). |
+| `POST /dispute` | Dispute path (`dispute_payment` ix). |
 
-## mountTrustGate
+Full route reference: [mountTrustGate](/sdk/mount-trustgate).
 
-`mountTrustGate(app, config)` adds x402 routes to an Express service in fewer than 50 lines.
+## Quick start — client
 
 ```ts
-await mountTrustGate(app, {
-  rpcUrl: "https://api.devnet.solana.com",
-  facilitatorKeypair,
-  defaultPolicyId: 1,
-  network: "solana-devnet",
-  atomicityEnforced: true,
+import { Keypair, PublicKey } from "@solana/web3.js";
+import { gatePayment } from "@agenttrust-sdk/trustgate/client";
+
+const decision = await gatePayment({
+  rpcUrl:          "https://api.devnet.solana.com",
+  caller:          facilitatorKeypair,
+  payerAgentAsset: new PublicKey("…"),
+  payeeAgentAsset: new PublicKey("…"),
+  amount:          1_000_000n,
+  mint:            new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC devnet
+  policyId:        1,
 });
+
+switch (decision.kind) {
+  case "Allow":             /* proceed */ break;
+  case "Deny":              console.log(decision.reasonName); break;
+  case "RequireValidation": /* route to attestation flow with decision.capabilityHash */ break;
+}
+```
+
+Full reference: [gatePayment](/sdk/gate-payment).
+
+## Atomic-tx invariant
+
+`gate_payment + SPL transfer + emit_feedback` MUST execute as one Solana transaction. Splitting them silently corrupts `VelocityLedger` when a Token-2022 mint's `TransferHook` extension reverts the transfer.
+
+The SDK enforces atomicity at three layers:
+
+```ts
+import {
+  AtomicityEnforced,
+  AtomicityNotEnforcedError,
+  composeAtomicSettleTx,
+} from "@agenttrust-sdk/trustgate";
+
+// 1. Compile-time literal-type guard:
+//    `AtomicityEnforced` is `{ atomicityEnforced: true }` (literal `true`).
+//    TS rejects `false`, missing, or `boolean` widening.
+//
+// 2. Runtime guard:
+//    `assertAtomicityEnforced` throws `AtomicityNotEnforcedError` for any
+//    value that isn't strictly `=== true`. Catches `as any` cast bypasses.
+//
+// 3. Composer structure:
+//    `composeAtomicSettleTx` returns one `Transaction` with exactly three
+//    instructions in canonical order (gate, transfer, feedback).
 ```
 
-## Atomicity guard
+Plus the on-chain Kani proof `gate_payment_strict_correctness` pins the strict handler's contract — `Ok(())` if and only if the composer returned `Allow`. Full proof: [Verification → Atomic-tx invariant](/verification/atomic-tx-invariant).
 
-`settle`, `dispute`, and middleware config require:
+## Breaking changes (0.2.0)
+
+`ProgramIds.trustgate` (lowercase) renamed to `ProgramIds.trustGate` (camelCase, matches `policyVault`). New `validationRegistry` field populated by default with the deployed devnet ID `Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`.
 
 ```ts
-{ atomicityEnforced: true }
+// 0.1.x
+DEFAULT_DEVNET_PROGRAM_IDS.trustgate.toBase58();
+
+// 0.2.0
+DEFAULT_DEVNET_PROGRAM_IDS.trustGate.toBase58();
+DEFAULT_DEVNET_PROGRAM_IDS.validationRegistry.toBase58(); // new
 ```
 
-The marker is literal `true`, not `boolean`, and the runtime guard throws if a caller bypasses TypeScript with a cast. The server adapter path extends this into proof validation and feedback emission.
+One-line migration: search-and-replace `.trustgate` → `.trustGate` for every `programIds.*` field access. Full changelog: [Reference → Changelog](/reference/changelog).
 
-## Current surface
+## On-chain programs (devnet)
 
-| API | Status |
-| --- | --- |
-| `gatePayment` | implemented |
-| `mountTrustGate` `/verify` | implemented |
-| `mountTrustGate` `/receipt` | implemented |
-| Pay.sh adapter | implemented in `@agenttrust/trustgate-server` workspace package |
-| Pay.sh demo | implemented in `examples/pay-sh-demo` |
-| `settle` | guarded SDK surface; server adapter validation path is active |
-| `dispute` | guarded SDK surface; negative feedback route remains narrower |
+<ProgramIdsTable />
+
+`loadPolicyVault` / `loadTrustGate` / `loadValidationRegistry` fetch each IDL from chain by default. Pass an explicit `idl` argument to use a bundled snapshot — useful when avoiding an extra RPC hop in latency-sensitive paths or when running against a freshly redeployed program before `anchor idl upgrade` runs.
+
+```bash
+anchor idl fetch <programId> --provider.cluster devnet
+```
+
+## Test coverage
+
+| Suite | Count | Where |
+|---|---:|---|
+| Atomicity unit tests | 6 (literal-type guard + runtime + composer structure) | `trustgate/sdk/test/atomicity.test.ts` |
+| PDA derivation tests | 24 | `trustgate/sdk/test/chain.test.ts` |
+| Quantu helpers | 12 | `trustgate/sdk/test/quantu.test.ts` |
+| ValidationRegistry instruction builders | 14 | `trustgate/sdk/test/validation-registry.test.ts` |
+| All SDK unit tests | 56 (+ 16 INTEGRATION-gated devnet round-trips) | `pnpm --filter ./trustgate/sdk run test` |
+
+Run via:
+
+```bash
+cd trustgate/sdk
+pnpm test
+INTEGRATION=1 pnpm test:integration   # devnet round-trip
+```
 
-Source: `trustgate/sdk/src`.
+## Read next
+
+<Cards>
+  <Card title="gatePayment" href="/sdk/gate-payment">
+    Read-only policy decision call — type signature, config fields, decision union, errors.
+  </Card>
+  <Card title="mountTrustGate" href="/sdk/mount-trustgate">
+    Express middleware reference — every route, every header, the atomicity guard contract.
+  </Card>
+  <Card title="Exports reference" href="/sdk/exports-reference">
+    One-screen list of every public export grouped by concern.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Three layers of proof + the on-chain Kani strict-correctness binding.
+  </Card>
+</Cards>

package/dist/embedded-docs/sdk/mount-trustgate.mdx

@@ -1,15 +1,185 @@
 ---
 title: mountTrustGate
-description: Express middleware that mounts AgentTrust x402 routes.
+description: Drop-in Express middleware. Adds the four x402 routes to any app — verify, receipt, settle, dispute — with the atomicity guard enforced at compile-time and runtime.
 ---
 
-`In progress`
+`mountTrustGate(app, config)` adds four endpoints to any Express app. The atomicity guard runs at the top of the call so a missing or `false` `atomicityEnforced` flag fails synchronously before any route binds.
 
-`mountTrustGate(app, config)` adds `/verify`, `/receipt`, `/settle`, and `/dispute` handlers to an Express service. The SDK enforces the atomicity config before binding routes.
+Source: [`trustgate/sdk/src/express.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/express.ts).
 
-| Source | Path |
-| --- | --- |
-| Express middleware | [`trustgate/sdk/src/express.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/express.ts) |
-| x402 helpers | [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts) |
-| atomicity tests | [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) |
+## Signature
 
+```ts
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+
+export function mountTrustGate(
+  app:    Application,
+  config: MountTrustGateConfig,
+): Promise<void>;
+```
+
+## `MountTrustGateConfig`
+
+```ts
+interface MountTrustGateConfig extends AtomicityEnforced {
+  rpcUrl:             string;       // Solana RPC URL
+  facilitatorKeypair: Keypair;      // signs emit_feedback CPIs + tx fees
+  defaultPolicyId?:   number;       // fallback if /verify body omits policyId
+  programIds?:        ProgramIds;   // defaults to DEFAULT_DEVNET_PROGRAM_IDS
+  network?:           string;       // x402 header label, e.g. "solana-devnet"
+  atomicityEnforced:  true;         // literal `true` — TS compile error on `false`
+}
+```
+
+The promise resolves once IDLs are loaded from the cluster and routes are bound. If the cluster doesn't have published IDLs, `mountTrustGate` rejects — call `anchor idl init` once per program before mounting.
+
+## Routes
+
+### `POST /verify`
+
+Read-only `gate_payment` simulation. Same semantics as [`gatePayment()`](/sdk/gate-payment).
+
+```http
+POST /verify
+Content-Type: application/json
+
+{
+  "payerAgentAsset": "<base58 pubkey>",
+  "payeeAgentAsset": "<base58 pubkey>",
+  "amount":          "1000000",
+  "mint":            "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "policyId":        1
+}
+```
+
+Responses:
+
+```http
+HTTP/1.1 200 OK
+X-Agent-Trust-Decision: Allow
+X-Payment-Network: solana-devnet
+```
+
+```http
+HTTP/1.1 402 Payment Required
+X-Agent-Trust-Decision: Deny
+X-Payment-Required: denied
+X-Payment-Reason-Code: 6
+X-Payment-Reason-Name: CounterpartyTierBelowMin
+X-Payment-Network: solana-devnet
+```
+
+```http
+HTTP/1.1 402 Payment Required
+X-Agent-Trust-Decision: RequireValidation
+X-Payment-Required: validation
+X-Capability-Required: 366c075140aa69746625d4b733b55e267fc5c28387fd6d1c24901976ee3ddc42
+X-Payment-Network: solana-devnet
+```
+
+Headers built via `buildHeadersForDecision` in [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts).
+
+### `GET /receipt/:paymentIdHashHex`
+
+`FeedbackEmissionLog` PDA lookup. Returns `{ exists: false }` until the payment settles.
+
+```http
+GET /receipt/6984738594e493bfd4314866840427a11e8e53677bc0ff4b98ae8aa39ce0c859
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "exists":          true,
+  "score":           100,
+  "isDispute":       false,
+  "emittedAtSlot":   460466788,
+  "feedbackEmissionLog": "HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3"
+}
+```
+
+The `paymentIdHashHex` parameter is the lowercase hex encoding of `SHA-256(payment_id_string)`. The SDK exports `deriveFeedbackLogPda(programId, paymentIdHashBytes)` for callers that derive the PDA themselves.
+
+### `POST /settle`
+
+Atomic settle path. The handler accepts the verify-time payment context plus the `tag1`/`tag2`/`endpoint`/`feedback_uri` metadata, builds the three-instruction transaction via `composeAtomicSettleTx`, and submits.
+
+```http
+POST /settle
+Content-Type: application/json
+
+{
+  "payerAgentAsset":     "<base58>",
+  "payeeAgentAsset":     "<base58>",
+  "amount":              "1000000",
+  "mint":                "<base58>",
+  "policyId":            1,
+  "paymentIdHash":       "6984738594e493bfd4314866840427a11e8e53677bc0ff4b98ae8aa39ce0c859",
+  "feedbackUri":         "ipfs://…",
+  "score":               100,
+  "tag1":                "successful",
+  "tag2":                "x402",
+  "endpoint":            "/protected"
+}
+```
+
+The route requires `payer` keypair access (the SPL transfer authority). The default Express handler reads it from `req.body.payerKey` for testing; production deploys typically wrap this route with their own auth + signature scheme. See [Pay.sh adapter](/integration-guides/pay-sh-adapter) for the canonical wrapping pattern.
+
+### `POST /dispute`
+
+Same shape as `/settle`, but invokes `dispute_payment` (negative-score feedback) instead. Requires `dispute_reason_hash` in the body. The same `FeedbackEmissionLog` idempotency rules apply: a second dispute for the same `payment_id_hash` fails account-already-in-use.
+
+## Atomicity guard
+
+`mountTrustGate` is itself a `MountTrustGateConfig extends AtomicityEnforced` consumer:
+
+```ts
+export interface MountTrustGateConfig extends AtomicityEnforced {
+  // … the literal `atomicityEnforced: true` is required
+}
+```
+
+```ts
+export async function mountTrustGate(app, config) {
+  assertAtomicityEnforced(config, "mountTrustGate");
+  // …
+}
+```
+
+Compile-time: `await mountTrustGate(app, { …, atomicityEnforced: false });` is a TS error. Runtime: `await mountTrustGate(app, { …, atomicityEnforced: true as any });` works because TS would have already let it through, BUT `await mountTrustGate(app, JSON.parse(unsafeUserConfig));` still fails the runtime guard.
+
+Six SDK unit tests cover both layers in [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) — including the `as any` cast bypass and the `composeAtomicSettleTx` three-instruction structure check.
+
+## Example
+
+```ts
+import express from "express";
+import { Keypair } from "@solana/web3.js";
+import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
+
+const app = express();
+app.use(express.json());
+
+const facilitatorKeypair = Keypair.fromSecretKey(
+  Uint8Array.from(JSON.parse(process.env.FACILITATOR_KEYPAIR!)),
+);
+
+await mountTrustGate(app, {
+  rpcUrl:             process.env.SOLANA_RPC_URL ?? "https://api.devnet.solana.com",
+  facilitatorKeypair,
+  defaultPolicyId:    1,
+  network:            "solana-devnet",
+  atomicityEnforced:  true,
+});
+
+app.get("/", (_req, res) => res.send("AgentTrust facilitator up"));
+app.listen(3000, () => console.log("listening on :3000"));
+```
+
+The hosted facilitator at [`api.agenttrust.tech`](https://api.agenttrust.tech) runs exactly this code path. Health: `GET /healthz`.
+
+## Source
+
+- Express middleware: [`trustgate/sdk/src/express.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/express.ts)
+- x402 helpers: [`trustgate/sdk/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/x402.ts)
+- Atomicity tests: [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts)

package/dist/embedded-docs/verification/adversarial-harness.mdx

@@ -0,0 +1,88 @@
+---
+title: Adversarial harness
+description: Fourteen hostile-scenario assertions that exercise the gate against malformed PDAs, replayed proofs, and corrupted state.
+---
+
+The adversarial harness sits alongside the Anchor end-to-end suite. While the e2e tests cover the happy + edge paths a normal integration would hit, the adversarial harness exercises the failure modes a hostile caller would try.
+
+Source: [`tests/adversarial.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/adversarial.spec.ts). Run via `anchor test --skip-deploy --provider.cluster localnet`.
+
+## The fourteen scenarios
+
+Each scenario constructs a hostile input and asserts the program rejects it with a typed error rather than producing an `Allow` or silently mutating state.
+
+| # | Scenario | Expected behaviour |
+|---:|---|---|
+| 1 | Forged `AtomStats` — wrong owner program | `Deny(AtomStatsWrongOwner)` (code 9) |
+| 2 | Forged `AtomStats` — schema-version canary mismatch | `Deny(AtomStatsSchemaMismatch)` (code 10) |
+| 3 | Forged `AtomStats` — tier byte > `ATOM_TIER_MAX = 4` | `Deny(AtomStatsSchemaMismatch)` (code 10) |
+| 4 | Forged `AtomStats` — undersized buffer | `Deny(AtomStatsSchemaMismatch)` (code 10) |
+| 5 | Replayed `payment_id_hash` | `account-already-in-use` on `FeedbackEmissionLog` init; whole tx reverts |
+| 6 | Self-pay attempt — facilitator signing as both payer and payee | `Deny` from facilitator-signer-mismatch check |
+| 7 | Wrong attestor — attestation issued by a key not in `accepted_attestors[]` | `Deny(AttestationAttestorRejected)` (code 14) |
+| 8 | Stale attestation — `expires_at <= now_slot` (and != 0) | `Deny(AttestationExpired)` (code 12) |
+| 9 | Revoked attestation — `revoked == true` | `Deny(AttestationRevoked)` (code 13) |
+| 10 | Wrong subject — attestation's `subject_asset` doesn't match the payee | `Deny(AttestationMissing)` (code 11) |
+| 11 | Wrong capability — attestation's `capability_hash` doesn't match `required_capability_hash` | `Deny(AttestationMissing)` (code 11) |
+| 12 | Multisig threshold bypass attempt — fewer distinct signers than `threshold` | `ThresholdNotMet` (Anchor error) |
+| 13 | Multisig duplicate-signer attempt — same key signing twice | counted as one (pubkey-dedup); `ThresholdNotMet` if remaining distinct count is below threshold |
+| 14 | Velocity counter manipulation — `now_slot < window_start_slot` (clock-skew or replay) | `saturating_sub` clamps elapsed to 0; window NOT expired; cumulative correctly preserved |
+
+## What the harness covers that Kani doesn't
+
+Kani's bounded model checker proves the pure-Rust composer's safety invariants over symbolic state. The adversarial harness covers the on-chain Anchor wrapper that Kani doesn't:
+
+- account-validation checks (owner mismatch, size mismatch, schema-version canary)
+- the `init`-only `FeedbackEmissionLog` + replay mechanism (Anchor's `account-already-in-use` semantics)
+- the Anchor-handler's signer constraints (facilitator self-pay, attestor key validation)
+- end-to-end on-chain tx behaviour the bounded composer can't see (idempotency, atomic revert)
+
+The two together cover both the in-program decision logic (Kani) and the surrounding Anchor wrapper (adversarial harness). Either alone leaves gaps.
+
+## Why localnet, not devnet
+
+Adversarial scenarios sometimes require constructing accounts the real Quantu programs would never produce (forged `AtomStats` with bad schema versions, forged `ValidationAttestation` PDAs with wrong owner). On localnet, the test fixture writes those raw bytes directly. On devnet, the only way to construct such an account is to compromise the real program — which we obviously can't do in CI.
+
+Localnet also produces deterministic timing for slot-based assertions (clock-skew test #14). Devnet cluster-time variance would make that test flaky.
+
+## Reproduce
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+anchor build
+anchor test --provider.cluster localnet --validator legacy --skip-build \
+  --grep "adversarial"
+```
+
+Expected: 14 / 14 passing in ~30 s.
+
+## Where it complements other layers
+
+- **PolicyVault unit tests (113 cases).** Cover normal paths through every policy module.
+- **Anchor TS e2e suite (50 cases).** Cover the Anchor wrapper happy paths against real (or cloned) Quantu state.
+- **Kani proofs (6 / 635 sub-checks).** Cover the pure-Rust composer's safety invariants over symbolic state.
+- **Adversarial harness (14 cases).** Cover the failure modes a hostile caller would try.
+- **MCP protocol conformance (21 cases).** Cover the MCP wire protocol shape.
+- **Adapter contract conformance (per-adapter test suites).** Cover the `FacilitatorAdapter` contract.
+
+The combination — 113 + 50 + 635 sub-checks + 14 + 21 + per-adapter — is what underwrites the v1 safety claim.
+
+## Source
+
+- Test file: [`tests/adversarial.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/adversarial.spec.ts)
+- Helper fixtures: [`tests/helpers/`](https://github.com/agenttrust-labs/agenttrust/tree/main/tests/helpers)
+
+## Read next
+
+<Cards>
+  <Card title="Kani proofs" href="/verification/kani-proofs">
+    The other side of the invariant proof — pure-Rust over symbolic state.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    The biggest scenario the harness covers — split-tx state corruption.
+  </Card>
+  <Card title="DenyReason codes" href="/reference/deny-reason-codes">
+    The 15 reason codes the harness asserts against.
+  </Card>
+</Cards>

package/dist/embedded-docs/verification/atomic-tx-invariant.mdx

@@ -0,0 +1,141 @@
+---
+title: Atomic-tx invariant
+description: gate_payment + transfer + emit_feedback execute as one Solana transaction or none. Three SDK layers + the on-chain Kani anchor + localnet runtime proof.
+---
+
+The load-bearing safety property of the SDK:
+
+> `gate_payment` + SPL `transferChecked` + `emit_feedback` MUST execute as one Solana transaction. Splitting them silently corrupts state when a Token-2022 mint's `TransferHook` extension reverts the transfer.
+
+Background writeup: [`docs/proofs/transfer-hook-atomicity.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/transfer-hook-atomicity.md). The proof is structured as five layers; all five must hold.
+
+## The corruption vector
+
+`gate_payment_strict` mutates state on `Allow`:
+
+- `PolicyAccount.spending_today_used`, `spending_today_anchor`, `spending_week_used`, `spending_week_anchor`
+- `VelocityLedger.cumulative_amount`, `last_commit_slot`, `window_start_slot`
+
+If a downstream SPL transfer reverts after that mutation — and the two instructions are in *different* Solana transactions — the gate's state is durable while no money has moved. Subsequent `gate_payment` calls read the inflated counters and may `Deny` a legitimate payment. In the inverse, counters can drift such that velocity caps appear hit when nothing real has happened.
+
+A Token-2022 `TransferHook` extension is the canonical instance of this fault model. The hook program runs synchronously inside the SPL `transferChecked` execution; if it returns `Err`, the transfer aborts. The specifics — compliance check, allowlist denial, freeze on suspicious counterparty — are domain-specific. From the runtime's perspective, a `TransferHook` revert is indistinguishable from any other inner-ix revert (NonTransferable mint, DefaultAccountState=Frozen, MissingRequiredSignature, out-of-funds). The atomicity guarantee is mint-extension-agnostic.
+
+## Five layers of proof
+
+| Layer | What it proves | Evidence |
+|---|---|---|
+| A.1 — compile-time guard | `AtomicityEnforced` is a literal `true` marker. TS rejects `false`, missing, and `boolean` widening at compile time. | [`trustgate/sdk/src/atomicity.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/atomicity.ts) lines 31-33 + [`test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) `describe("AtomicityEnforced literal-type guard")` |
+| A.2 — 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 + 6-case test suite |
+| A.3 — composer structure | `composeAtomicSettleTx` returns ONE `Transaction` with EXACTLY 3 instructions in canonical order — gate (PolicyVault) + `transferChecked` (Token / Token-2022) + `emit_feedback` (TrustGate). | [`trustgate/sdk/test/atomicity.test.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/test/atomicity.test.ts) `describe("composeAtomicSettleTx")` (5 cases including Token-2022 program-id propagation) |
+| B — single-tx atomic revert | When the bundled tx contains a failing inner ix, Solana reverts the entire bundle; `gate_payment_strict`'s state mutation rolls back. PolicyAccount + VelocityLedger stay clean. | [`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")` |
+| C — split-tx corruption (anti-pattern) | If a caller splits the bundle into two txs, gate_payment_strict commits in tx1, the failing transfer reverts in tx2, and VelocityLedger is left dirty (counted a payment that never moved). This is the corruption vector A + B prevent. | [`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 #6, 258 sub-checks) — strict handler returns `Ok(())` if and only if the lazy composer returns `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) |
+
+## A — SDK type + runtime guards
+
+```ts
+export interface AtomicityEnforced {
+  readonly atomicityEnforced: true;     // literal true, not boolean
+}
+
+export class AtomicityNotEnforcedError extends Error {
+  constructor(siteName: string) {
+    super(`[${siteName}] atomicityEnforced=true is required …`);
+    this.name = "AtomicityNotEnforcedError";
+  }
+}
+
+export function assertAtomicityEnforced(
+  cfg: { atomicityEnforced?: unknown },
+  siteName: string,
+): void {
+  if ((cfg as any).atomicityEnforced !== true) {
+    throw new AtomicityNotEnforcedError(siteName);
+  }
+}
+```
+
+Compile-time: `composeAtomicSettleTx({ …, atomicityEnforced: false })` is a TS error. Runtime: `composeAtomicSettleTx({ …, atomicityEnforced: 1 } as any)` throws `AtomicityNotEnforcedError("composeAtomicSettleTx")`. Both layers required: skipping either re-opens the corruption vector.
+
+## A.3 — Composer structure
+
+`composeAtomicSettleTx` returns:
+
+```ts
+interface ComposedAtomicSettle {
+  readonly tx: Transaction;
+  readonly instructions: ReadonlyArray<TransactionInstruction>;  // exactly 3
+  readonly accounts: { … };
+}
+```
+
+The three instructions, in order:
+
+1. `gate_payment_strict` — `Err` on `Deny` / `RequireValidation`. Reverts the whole bundle if the gate denies.
+2. SPL `transferChecked` (legacy Token or Token-2022 — `tokenProgram` arg switches).
+3. `emit_feedback` — PDA-signed CPI into Quantu via TrustGate.
+
+Five test cases pin this contract — including a Token-2022 program-id propagation case that ensures the SPL ix uses `TOKEN_2022_PROGRAM_ID` when the caller passes it.
+
+## B+C — Localnet runtime proofs
+
+The Anchor TS test [`tests/atomic-tx-invariant.spec.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/tests/atomic-tx-invariant.spec.ts) splits into two `describe` blocks:
+
+- **`B. single-tx atomic revert`.** Builds the bundled tx with an intentionally-failing System.transfer (source keypair never signs → guaranteed `MissingRequiredSignature`) and asserts the entire bundle reverts; PolicyAccount + VelocityLedger remain in their pre-tx state.
+- **`C. split-tx anti-pattern corrupts state`.** Splits the same flow into two transactions. Tx 1 commits the gate's velocity update. Tx 2 reverts on the failing transfer. The ledger now reflects a payment that never moved — the corruption vector that B prevents.
+
+### Why System.transfer instead of TransferHook
+
+The localnet tests deliberately use a System.transfer with a never-signed source as the failing inner instruction. This:
+
+1. Exercises the same Solana atomicity semantics a `TransferHook` revert would — the runtime aborts the bundle, all child mutations roll back.
+2. Requires no Token-2022 mint setup or custom hook program on the localnet validator, keeping the test focused on the property under proof rather than mint-init plumbing.
+3. Documents the corruption vector at the layer where it actually matters: any failing inner ix corrupts split-tx state. `TransferHook` is one specific failure mode, not the property itself.
+
+The Token-2022 angle is fully covered at the SDK layer in `composeAtomicSettleTx` test cases.
+
+## On-chain Kani anchor
+
+The strict handler's contract is pinned by Kani `gate_payment_strict_correctness`:
+
+- `strict_returns_ok_iff_allow` — `Ok(())` ⇔ `Allow`. 131 sub-checks.
+- `gate_decision_is_one_of_three_disjoint_variants` — three arms pairwise disjoint; a fourth variant cannot silently slip past. 127 sub-checks.
+
+Combined: 258 sub-checks, ~0.9 s. Sub-check 0 failed. If a future change re-routes the `Deny` arm to an `Ok` return, both proofs fail loud.
+
+The on-chain anchor + the SDK guards together close the corruption vector at three layers: compile, runtime, and on-chain.
+
+## Reproduce
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+
+# A — SDK layers
+cd trustgate/sdk
+pnpm test                      # 6 atomicity-specific cases + 50 others
+
+# B + C — localnet
+cd ../..
+anchor build
+anchor test --provider.cluster localnet --validator legacy --skip-build
+
+# On-chain anchor (Kani)
+cd programs/policy-vault
+cargo kani --harness strict_returns_ok_iff_allow
+cargo kani --harness gate_decision_is_one_of_three_disjoint_variants
+```
+
+## Read next
+
+<Cards>
+  <Card title="Kani proofs" href="/verification/kani-proofs">
+    Per-harness deep-dive on all 6 invariants.
+  </Card>
+  <Card title="Composer" href="/programs/policy-vault/composer">
+    The pure-Rust orchestration the strict handler wraps.
+  </Card>
+  <Card title="mountTrustGate" href="/sdk/mount-trustgate">
+    Where the SDK consumer plugs into the atomicity guard.
+  </Card>
+</Cards>