@agenttrust-sdk/mcp 0.2.5 → 0.3.0

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

@@ -1,68 +1,98 @@
 ---
 title: PolicyVault
-description: The policy composer that returns Allow, Deny, or RequireValidation.
+description: The decision engine — five orthogonal policy kinds composed under one gate_payment instruction with fail-fast semantics.
 ---
 
-PolicyVault is the decision engine for AgentTrust. It reads payer, payee, policy, velocity, kill-switch, and optional attestation data, then returns a `GateDecision`.
-
-## Composer order
-
-The order is fixed and fail-fast:
-
-| Order | Policy | Why it runs there |
-| --- | --- | --- |
-| 1 | `KillSwitch` | cheapest global stop |
-| 2 | `Spending` | pure amount and calendar bounds |
-| 3 | `Velocity` | sliding-window spend bound keyed by payer tier |
-| 4 | `CounterpartyTier` | reads payee AtomStats trust data |
-| 5 | `RequireValidation` | reads the attestation PDA last |
-
-```rust
-pub fn compose_decision(input: ComposerInput) -> ComposerResult {
-    // KillSwitch -> Spending -> Velocity -> CounterpartyTier -> RequireValidation
-    // On Allow, deltas are returned for the Anchor wrapper to apply.
-    // On Deny or RequireValidation, deltas are None.
-}
-```
-
-## Decision shape
+PolicyVault is the program that turns "should this payment go through?" into a typed `GateDecision`. It reads the payer agent, the payee agent, the policy account, the velocity ledger, the kill switch, the payer's `AtomStats` (Quantu), the payee's `AtomStats`, and an optional `ValidationAttestation`, then returns one of three values:
 
 ```rust
 pub enum GateDecision {
     Allow,
     Deny(DenyReason),
-    RequireValidation([u8; 32]),
+    RequireValidation([u8; 32]),  // capability_hash
 }
 ```
 
-`DenyReason::code()` is stable for clients even though the Borsh enum order is internal to Anchor.
+**Devnet:** [`8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR`](https://explorer.solana.com/address/8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR?cluster=devnet)
 
-## Policy kinds
+## Instructions
 
-| Policy | Inputs | State mutation on Allow |
-| --- | --- | --- |
-| Spending | `amount`, UTC day, ISO week | daily and weekly counters |
-| Velocity | `amount`, slot window, payer tier | `VelocityLedger.cumulative_amount` |
-| CounterpartyTier | payee tier, risk, confidence | none |
-| RequireValidation | subject, capability hash, attestor, expiry | none |
-| KillSwitch | per-agent paused flag | none |
+| Instruction | Effect |
+|---|---|
+| `init_authority` | Create `PolicyAuthority` PDA with multisig members + threshold |
+| `init_killswitch` | Create `KillSwitchState` PDA (per-agent / per-collection / global) |
+| `init_policy` | Create `PolicyAccount` + `VelocityLedger` for `(agent, policy_id)` |
+| `set_killswitch` | Pause / unpause; multisig-gated against `PolicyAuthority` |
+| `gate_payment` | Lazy decision — returns `Allow` / `Deny(reason)` / `RequireValidation(hash)` |
+| `gate_payment_strict` | Strict variant — returns `Ok(())` iff `Allow`, else `Err`. The SDK's atomic composer uses this. |
 
-## Safety rule
+The strict variant is the load-bearing one for atomicity. Phase J5 added a Kani proof, `gate_payment_strict_correctness`, that pins `strict_returns_ok_iff_allow` (a biconditional) and `gate_decision_is_one_of_three_disjoint_variants`. A future change that re-routes the `Deny` arm to an `Ok` return fails the proof loud.
 
-The Anchor handler snapshots all accounts before composing, then applies returned deltas only when the decision is `Allow`.
+## State accounts
 
-```rust
-match result.decision {
-    GateDecision::Allow => {
-        spending::apply_deltas(&mut ctx.accounts.policy_account, d);
-        velocity::apply_deltas(&mut ctx.accounts.velocity_ledger, d);
-    }
-    GateDecision::Deny(_) | GateDecision::RequireValidation(_) => {}
-}
-```
+| PDA | Seeds | Size | Role |
+|---|---|---:|---|
+| `PolicyAuthority` | `["policy_authority", agent_asset]` | 272 | Multisig members + threshold (1..=7) |
+| `KillSwitchState` | `["killswitch", scope_kind, scope_key]` | 96 | Emergency pause flag + audit trail |
+| `PolicyAccount` | `["policy", agent_asset, policy_id_le]` | 240 | Per-policy config + lazy counters |
+| `VelocityLedger` | `["velocity", agent_asset, policy_id_le]` | 80 | Sliding-window cumulative-spend counter |
+
+Per-program byte layouts live on each policy page (linked below). The full `PolicyAccount` declaration is in [`programs/policy-vault/src/state/policy_account.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_account.rs).
 
-## Formal checks
+## The composer
+
+`gate_payment` is a thin Anchor wrapper around the pure-Rust `compose_decision` function. The wrapper:
+
+1. Snapshots all read accounts into plain Rust structs (`PolicySnapshot`, `VelocityLedgerSnapshot`, `KillSwitchSnapshot`, optional `AtomStatsView` ×2, optional `ValidationAttestationView`).
+2. Calls `compose_decision(input)`.
+3. On `Allow`, applies the returned `SpendingDeltas` and `VelocityDeltas` to `PolicyAccount` and `VelocityLedger` respectively.
+4. On `Deny` or `RequireValidation`, mutates nothing.
+
+Order is fixed and fail-fast:
+
+| # | Policy | Cost | Fails fast on |
+|---:|---|---|---|
+| 1 | [KillSwitch](/programs/policy-vault/kill-switch-policy) | cheapest (one bool) | `paused == true` |
+| 2 | [Spending](/programs/policy-vault/spending-policy) | pure arithmetic | per-tx / daily / weekly limits |
+| 3 | [Velocity](/programs/policy-vault/velocity-policy) | one PDA read | sliding-window cap |
+| 4 | [CounterpartyTier](/programs/policy-vault/counterparty-tier-policy) | two `AtomStats` PDA reads | tier / risk / confidence |
+| 5 | [RequireValidation](/programs/policy-vault/require-validation-policy) | one attestation PDA read | subject / capability / expiry / attestor |
+
+Full composer reference: [Composer](/programs/policy-vault/composer).
+
+## DenyReason codes
+
+`DenyReason` is the enum returned in the `Deny` arm. The Borsh wire format follows declaration order, but clients should consume the stable numeric `code()` instead — it is decoupled from Borsh field order.
+
+| Code | Variant | Originating policy |
+|---:|---|---|
+| 1 | `KillSwitchEngaged` | KillSwitch |
+| 2 | `SpendingPerTxExceeded` | Spending |
+| 3 | `SpendingDailyExceeded` | Spending |
+| 4 | `SpendingWeeklyExceeded` | Spending |
+| 5 | `VelocityWindowExceeded` | Velocity |
+| 6 | `CounterpartyTierBelowMin` | CounterpartyTier |
+| 7 | `CounterpartyRiskAboveMax` | CounterpartyTier |
+| 8 | `CounterpartyConfidenceBelow` | CounterpartyTier |
+| 9 | `AtomStatsWrongOwner` | CounterpartyTier (defensive) |
+| 10 | `AtomStatsSchemaMismatch` | CounterpartyTier (defensive) |
+| 11 | `AttestationMissing` | RequireValidation |
+| 12 | `AttestationExpired` | RequireValidation |
+| 13 | `AttestationRevoked` | RequireValidation |
+| 14 | `AttestationAttestorRejected` | RequireValidation |
+| 15 | `UnratedTreatmentDeny` | CounterpartyTier (Unrated → Deny resolution) |
+
+Full table with remediation hints: [Reference → DenyReason codes](/reference/deny-reason-codes).
+
+## Formal verification
 
 <KaniProofBadge />
 
-Source: `programs/policy-vault/src/policies/composer.rs`.
+Six Kani harnesses run on every PR via [`.github/workflows/kani-prove.yml`](https://github.com/agenttrust-labs/agenttrust/blob/main/.github/workflows/kani-prove.yml). Per-harness deep-dive: [Verification → Kani proofs](/verification/kani-proofs).
+
+## Source
+
+- Program entry: [`programs/policy-vault/src/lib.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/lib.rs)
+- Composer: [`programs/policy-vault/src/policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs)
+- DenyReason: [`programs/policy-vault/src/state/decision.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/decision.rs)
+- Kani proofs: [`programs/policy-vault/src/proofs/`](https://github.com/agenttrust-labs/agenttrust/tree/main/programs/policy-vault/src/proofs)

package/dist/embedded-docs/programs/policy-vault/kill-switch-policy.mdx

@@ -1,15 +1,72 @@
 ---
 title: KillSwitch policy
-description: Multisig-gated pause control for PolicyVault decisions.
+description: First in the composer — a multisig-controlled emergency pause that blocks any Allow when paused.
 ---
 
-`In progress`
+KillSwitch is the cheapest policy and runs first. When the agent's `KillSwitchState.paused == true`, the composer returns `Deny(KillSwitchEngaged)` immediately — no other policy or foreign-PDA read costs are paid.
 
-KillSwitch is the first policy in the composer. When it is paused, the composer cannot return `Allow`.
+Source: [`programs/policy-vault/src/policies/killswitch.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/killswitch.rs).
 
-| Source | Path |
-| --- | --- |
-| evaluator | [`programs/policy-vault/src/policies/killswitch.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/killswitch.rs) |
-| pause instruction | [`programs/policy-vault/src/instructions/set_killswitch.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/set_killswitch.rs) |
-| proof | [`programs/policy-vault/src/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) |
+## State
 
+```rust
+#[account]
+pub struct KillSwitchState {
+    pub scope_kind: u8,        // off  8 — Global / PerCollection / PerAgent
+    pub bump: u8,              // off  9
+    pub paused: bool,          // off 10 — the bit
+    pub _pad0: u8,             // off 11
+    pub _pad1: [u8; 4],        // off 12..16
+    pub scope_key: [u8; 32],   // off 16..48 — zeros for Global
+    pub paused_at_slot: u64,   // off 48..56
+    pub unpaused_at_slot: u64, // off 56..64
+    pub paused_by: Pubkey,     // off 64..96
+}
+```
+
+PDA seeds: `["killswitch", &[scope_kind], scope_key]`. Three scope kinds — global, per-collection, per-agent — all share the same struct.
+
+## Mutation — `set_killswitch`
+
+The pause flag flips through the `set_killswitch` instruction, which is multisig-gated against the agent's `PolicyAuthority`. The Anchor handler checks:
+
+```rust
+let distinct = authority.count_distinct_signing_members(&signer_keys);
+require!(
+    distinct >= authority.threshold,
+    PolicyVaultError::ThresholdNotMet,
+);
+```
+
+`count_distinct_signing_members` is pubkey-based: a single signer signing twice counts as one. Even if `PolicyAuthority.members` somehow contained duplicates (the `init_authority` constraint rejects this, but defense in depth), the count cannot exceed `min(member_count, signer_keys.len())`. That is the load-bearing property of `multisig_threshold_enforced` (Kani #5, 149 sub-checks, 77.17 s).
+
+`PolicyAuthority` carries up to 7 members + a `threshold` (default 2). Source: [`programs/policy-vault/src/state/policy_authority.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_authority.rs).
+
+## Pure decision function
+
+```rust
+pub fn evaluate(state: KillSwitchSnapshot) -> Option<DenyReason> {
+    if state.paused {
+        Some(DenyReason::KillSwitchEngaged)
+    } else {
+        None
+    }
+}
+```
+
+`Some(KillSwitchEngaged)` short-circuits the composer to `GateDecision::Deny(KillSwitchEngaged)` (DenyReason code `1`).
+
+## Formal verification
+
+`paused_implies_no_allow` (Kani #1, 126 sub-checks, 0.25 s) — 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. The load-bearing safety invariant of the gate.
+
+If a future change re-orders or skips KillSwitch evaluation, this proof fails loud. Reference: [Verification → Kani proofs](/verification/kani-proofs).
+
+## Source
+
+- Policy module: [`policies/killswitch.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/killswitch.rs)
+- State: [`state/kill_switch_state.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/kill_switch_state.rs)
+- Mutation: [`instructions/set_killswitch.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/set_killswitch.rs)
+- Authority: [`state/policy_authority.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_authority.rs)
+- Kani proof: [`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)
+- Multisig Kani proof: [`proofs/inv_multisig_threshold_enforced.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_multisig_threshold_enforced.rs)

package/dist/embedded-docs/programs/policy-vault/require-validation-policy.mdx

@@ -1,15 +1,83 @@
 ---
 title: RequireValidation policy
-description: Capability-attestation checks for payments that need validation evidence.
+description: Gate against a ValidationAttestation PDA — capability hash, expiry, revocation, and per-policy attestor whitelist.
 ---
 
-`In progress`
+RequireValidation is the fifth and last policy. Reads one `ValidationAttestation` PDA from AgentTrust's `validation-registry` program, then checks subject, capability, revocation, expiry, and an optional per-policy attestor whitelist.
 
-RequireValidation returns `RequireValidation` when the required capability is missing, and returns `Deny` when the supplied attestation is expired, revoked, or not issued by an accepted attestor.
+Source: [`programs/policy-vault/src/policies/require_validation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/require_validation.rs). Parser: [`programs/policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs).
 
-| Source | Path |
-| --- | --- |
-| evaluator | [`programs/policy-vault/src/policies/require_validation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/require_validation.rs) |
-| attestation parser | [`programs/policy-vault/src/ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs) |
-| proof | [`programs/policy-vault/src/proofs/inv_validation_expiry_correct.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_validation_expiry_correct.rs) |
+## Reads from `ValidationAttestation`
 
+| Offset | Width | Field |
+|---:|---:|---|
+| `8`   | Pubkey | `subject_asset` |
+| `40`  | [u8; 32] | `capability_hash` |
+| `72`  | Pubkey | `attestor` |
+| `208` | u64 LE | `expires_at` (0 = never expires) |
+| `216` | bool | `revoked` |
+
+Account size: `VALIDATION_ATTESTATION_SIZE = 290`. The remaining bytes (signed message hash, claim URI hash, claim payload hash, issued_at, revocation reason hash, bump) are not read by the policy in v1 — they live on the PDA for audit-trail integrity but the parser only loads what the gate decides on.
+
+ValidationRegistry pinned program ID (devnet): [`Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv`](https://explorer.solana.com/address/Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv?cluster=devnet).
+
+## Policy state (subset of `PolicyAccount`)
+
+```rust
+pub required_capability_hash: [u8; 32],   // off 135..167 — zeros = policy not enabled
+pub accepted_attestors: [Pubkey; 2],      // off 167..231 — both zeros = permissionless
+```
+
+The `required_capability_hash` is the SHA-256 of a UTF-8 capability name (e.g., `kyc.tier-1.v1` → `366c075140aa…ddc42`). When zero, the policy is effectively a pass-through. When set, every payment to this `(agent, policy_id)` requires an attestation matching that hash.
+
+`accepted_attestors` is a 2-slot whitelist. Both zeros = permissionless (any registered attestor's signature flips the gate to `Allow`). Otherwise only attestations from those keys count.
+
+## Decision
+
+```
+1. required_capability_hash == 0      → Allow (policy not configured)
+2. attestation == None                → RequireValidation(required_capability_hash)
+3. view.subject_asset != payee_asset  → Deny(AttestationMissing)             code 11
+4. view.capability_hash != required   → Deny(AttestationMissing)             code 11
+5. view.revoked                        → Deny(AttestationRevoked)            code 13
+6. view.expires_at != 0 AND
+   view.expires_at <= now_slot         → Deny(AttestationExpired)            code 12
+7. !permissionless AND attestor not in whitelist
+                                       → Deny(AttestationAttestorRejected)   code 14
+8. else                                → Allow
+```
+
+`expires_at == 0` is the "never expires" sentinel. `expires_at == now_slot` is treated as expired (the playbook bound: `expires_at > now` ⇒ not expired; equality fails).
+
+When the attestation account is uninitialised (no rent or empty data), the policy returns `RequiresAttestation(capability_hash)` and the composer surfaces `GateDecision::RequireValidation(hash)` to the facilitator. The facilitator routes the user through the off-chain attestation flow → `request_validation` → attestor responds → `respond_to_validation` writes the PDA → re-submit payment → gate now reads the new attestation and returns `Allow`. End-to-end devnet trace: [Verification → Chained validation](/verification/chained-validation).
+
+## Three-way outcome
+
+```rust
+pub enum RequireValidationOutcome {
+    Allow,
+    Deny(DenyReason),
+    RequiresAttestation([u8; 32]),  // composer maps to RequireValidation
+}
+```
+
+This is the only policy that returns a non-`Allow`/`Deny` shape. The composer's job is to bubble `RequiresAttestation(hash)` up as `GateDecision::RequireValidation(hash)` so the facilitator's `formatChallenge` can include the capability hash in the x402 response headers (`X-Capability-Required`).
+
+## Per-policy attestor filtering
+
+The v1 sybil-resistance model is "permissionless registration plus opinionated downstream filtering". Anyone can register as an attestor or a capability namespace. PolicyVault decides per-policy which attestors it trusts via `accepted_attestors[]`. A policy that gates against `audit.smart-contract.v1` might only accept attestations from Halborn or OtterSec; a policy that gates against `kyc.tier-1.v1` might accept any registered KYC attestor.
+
+The trade-off is local trust over global gatekeeping — the only model that scales with the number of facilitators. Ten canonical v1 namespaces are already seeded on devnet: [Reference → Capability namespaces](/reference/capability-namespaces).
+
+## Formal verification
+
+- `validation_expiry_correct` (Kani #4, 85 sub-checks, 0.23 s) — an expired attestation (`expires_at != 0 AND expires_at <= now_slot`) cannot produce `Allow` from `require_validation::evaluate`. Subject + capability + revocation are forced equal so expiry is the deciding gate. Closes the obvious time-of-check / time-of-use stale-attestation hole.
+
+In-module tests cover the zero-hash pass-through, missing-attestation `RequiresAttestation`, wrong-subject and wrong-capability denials, revocation, expiry boundaries (`expires_at == now`, `expires_at == 0`, `expires_at > now`), and whitelist with both 1-slot and 2-slot configurations.
+
+## Source
+
+- Policy module: [`policies/require_validation.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/require_validation.rs)
+- ValidationAttestation parser: [`ext/validation_registry.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/ext/validation_registry.rs)
+- Kani proof: [`proofs/inv_validation_expiry_correct.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/proofs/inv_validation_expiry_correct.rs)
+- ValidationRegistry program: [ValidationRegistry](/programs/validation-registry)

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

@@ -1,15 +1,90 @@
 ---
 title: Spending policy
-description: Per-transaction, daily, and weekly limits enforced before payment settlement.
+description: Per-transaction, daily (UTC midnight), and weekly (ISO Monday) limits with anchor-rollover math.
 ---
 
-`In progress`
+Spending is the second policy in the composer. Pure arithmetic — no foreign PDA reads. Three constraints in order: per-tx max, daily max, weekly max.
 
-The Spending policy gates a payment against configured per-transaction, daily, and weekly limits. Allow-path deltas are applied only after the full PolicyVault composer returns `Allow`.
+Source: [`programs/policy-vault/src/policies/spending.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/spending.rs).
 
-| Source | Path |
-| --- | --- |
-| evaluator | [`programs/policy-vault/src/policies/spending.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/spending.rs) |
-| composer | [`programs/policy-vault/src/policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs) |
-| policy init | [`programs/policy-vault/src/instructions/init_policy.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/init_policy.rs) |
+## State (subset of `PolicyAccount`)
 
+```rust
+pub spending_per_tx_max: u64,    // off 50..58
+pub spending_daily_max: u64,     // off 58..66
+pub spending_weekly_max: u64,    // off 66..74
+pub spending_today_used: u64,    // off 74..82  — anchor-relative counter
+pub spending_week_used: u64,     // off 82..90  — anchor-relative counter
+pub spending_today_anchor: u64,  // off 90..98  — day index since 1970-01-01
+pub spending_week_anchor: u64,   // off 98..106 — week index since 1970-01-05 (Mon)
+```
+
+Per-policy snapshots are extracted via `From<&PolicyAccount> for SpendingState`. The composer never mutates these fields directly — `apply_deltas` does, only on the `Allow` branch.
+
+## Decision order
+
+```rust
+1. amount == 0           → Allow (no-op deltas)
+2. amount > per_tx_max   → Deny(SpendingPerTxExceeded)              code 2
+3. today_used + amount > daily_max  → Deny(SpendingDailyExceeded)   code 3
+4. week_used  + amount > weekly_max → Deny(SpendingWeeklyExceeded)  code 4
+5. else                  → Allow with new today/week counters + anchors
+```
+
+All comparisons use `checked_add`; overflow returns `Deny(SpendingDailyExceeded)` (the daily check is the first to overflow under realistic configs).
+
+## Anchor rollover
+
+`today_anchor` is `floor(unix_ts / 86_400)` — the day index since the Unix epoch. `week_anchor` is `floor((unix_ts - 4 × 86_400) / (7 × 86_400))` — the week index since Monday 1970-01-05 (the first Monday after the Unix epoch, which was a Thursday).
+
+When the cluster's current `unix_ts` falls into a new day, the policy treats `today_used_effective = 0` (rollover); the same logic applies to weekly. The new anchor is written back along with the new counter on `Allow`.
+
+```rust
+let today_used_effective = if state.today_anchor == today_anchor_now {
+    state.today_used
+} else {
+    0
+};
+```
+
+The week anchor is biased to ISO Monday — `1970-01-05` was a Monday; subsequent weeks roll at Monday 00:00 UTC. The day anchor uses pure UTC midnight.
+
+## Pure decision function
+
+```rust
+pub fn evaluate(state: SpendingState, amount: u64, unix_ts: i64) -> SpendingOutcome;
+
+pub enum SpendingOutcome {
+    Allow(SpendingDeltas),
+    Deny(DenyReason),
+}
+
+pub struct SpendingDeltas {
+    pub new_today_used:  u64,
+    pub new_week_used:   u64,
+    pub new_today_anchor: u64,
+    pub new_week_anchor: u64,
+}
+```
+
+The composer applies deltas via `spending::apply_deltas(account, &deltas)` only when every policy returns `Allow`. The deltas are computed but never written if a later policy denies — that is the rule that makes `velocity_counter_le_limit` (Kani #2) inductive.
+
+## Formal verification
+
+The Spending policy is exercised by the composer-level `gate_payment_strict_correctness` proof (Kani #6, 258 sub-checks). Spending-specific behaviour is covered by the 14 in-module unit tests, including:
+
+- `happy_path_writes_amount_to_both_counters`
+- `deny_per_tx_exceeded` / `deny_daily_exceeded_with_existing_usage` / `deny_weekly_exceeded_with_existing_usage`
+- `rollover_resets_daily_when_anchor_changes` / `rollover_resets_weekly_when_anchor_changes`
+- `overflow_is_treated_as_daily_exceeded`
+- `boundary_amount_at_daily_max_allows`
+- `negative_unix_ts_clamps_to_zero_anchors`
+
+Source: [`programs/policy-vault/src/policies/spending.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/spending.rs) — 301 lines including tests.
+
+## Source
+
+- Policy module: [`policies/spending.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/spending.rs)
+- Composer: [`policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs)
+- State: [`state/policy_account.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/policy_account.rs)
+- Init instruction: [`instructions/init_policy.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/instructions/init_policy.rs)

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

@@ -1,15 +1,92 @@
 ---
 title: Velocity policy
-description: Sliding-window payment counters with tier-adjusted limits.
+description: Sliding-window cumulative-spend counter with payer-tier-decayed window size and Allow-only ledger commit.
 ---
 
-`In progress`
+Velocity is the third policy. One PDA read (`VelocityLedger`), then pure arithmetic. The window size is decayed by the payer's `trust_tier` so a tier-0 agent gets a tighter throttle than a tier-3 agent.
 
-The Velocity policy applies a rolling counter before a payment can proceed. The composer carries velocity deltas only on the all-policies-allowed branch.
+Source: [`programs/policy-vault/src/policies/velocity.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/velocity.rs).
 
-| Source | Path |
-| --- | --- |
-| evaluator | [`programs/policy-vault/src/policies/velocity.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/velocity.rs) |
-| account state | [`programs/policy-vault/src/state/velocity_ledger.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/velocity_ledger.rs) |
-| proof | [`programs/policy-vault/src/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) |
+## `VelocityLedger` PDA
 
+```rust
+#[account]
+pub struct VelocityLedger {
+    pub payer_agent_asset: Pubkey, // off  8..40
+    pub policy_id: u32,            // off 40..44
+    pub bump: u8,                  // off 44
+    pub _pad0: [u8; 3],            // off 45..48
+    pub cumulative_amount: u64,    // off 48..56 — sum across active window
+    pub last_commit_slot: u64,     // off 56..64 — slot of last Allow
+    pub window_start_slot: u64,    // off 64..72 — first commit slot in current window
+    pub _reserved: [u8; 8],        // off 72..80
+}
+```
+
+PDA seeds: `["velocity", payer_agent_asset, policy_id_le_bytes]`. Account size: 80 bytes.
+
+## Tier-decayed window
+
+| Payer tier | Multiplier | Effective window |
+|---:|---:|---|
+| 0 (untrusted) | 1/4 | window × 0.25 |
+| 1 | 2/4 | window × 0.50 |
+| 2 | 3/4 | window × 0.75 |
+| 3 (Gold, default) | 4/4 | window × 1.00 |
+| 4 (Platinum) | 5/4 | window × 1.25 |
+
+```rust
+pub fn apply_tier_decay(base_secs: u64, payer_tier: u8) -> u64;
+```
+
+Computed in `u128` to avoid overflow on tier-4 over very large bases; clamps to `u64::MAX` if the multiplied result overflows. Unknown tier (`tier > 4` — corruption canary) falls back to Gold (1×) — conservative-but-not-locking.
+
+`SLOTS_PER_SECOND = 2` (the conservative envelope per `docs/plan/research/04-policyvault-build-playbook.md §E.1`). `window_slots = effective_window_secs × 2`.
+
+## Decision
+
+```rust
+pub fn evaluate(
+    state: VelocityState,
+    ledger: VelocityLedgerSnapshot,
+    amount: u64,
+    payer_tier: u8,
+    now_slot: u64,
+) -> VelocityOutcome;
+```
+
+```
+1. amount == 0  → Allow with no-op deltas (last_commit advances, window not reset)
+2. elapsed = saturating_sub(now_slot, window_start_slot)
+3. if elapsed ≥ window_slots → window expired → reset cumulative to 0
+4. new_cumulative = active_in_window + amount  (checked_add → Deny on overflow)
+5. if new_cumulative > max_in_window → Deny(VelocityWindowExceeded)         code 5
+6. else                              → Allow with new_cumulative + (maybe) new window_start_slot
+```
+
+`saturating_sub` on `now_slot` ensures clock-skew or replay scenarios where `now_slot < window_start_slot` clamp `elapsed` to 0 — window NOT expired, defensive.
+
+## Allow-only commit
+
+The Velocity policy never writes to `VelocityLedger` directly. The composer's Anchor wrapper applies `velocity::apply_deltas(&mut ledger, &deltas)` only when every prior + later policy returns `Allow`. That is what makes `velocity_counter_le_limit` (Kani #2) inductive: every prior `Allow` preserves `cumulative_amount ≤ max_in_window`; a fresh ledger trivially satisfies the base case.
+
+```rust
+pub struct VelocityDeltas {
+    pub new_cumulative_amount:  u64,
+    pub new_last_commit_slot:   u64,
+    pub new_window_start_slot:  u64,
+}
+```
+
+## Formal verification
+
+- `velocity_counter_le_limit` (Kani #2, 9 sub-checks, 0.03 s) — 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. Cross-policy preservation against `spending.weekly_max` is a separate proof if/when needed.
+
+In-module unit tests cover tier decay (5 cases), window expiry, boundary cases at `max_in_window`, overflow, `max_in_window == 0`, and `now_slot < window_start_slot`. Source: [`programs/policy-vault/src/policies/velocity.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/velocity.rs) — 339 lines.
+
+## Source
+
+- Policy module: [`policies/velocity.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/velocity.rs)
+- State: [`state/velocity_ledger.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/state/velocity_ledger.rs)
+- Composer: [`policies/composer.rs`](https://github.com/agenttrust-labs/agenttrust/blob/main/programs/policy-vault/src/policies/composer.rs)
+- Kani proof: [`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)