# TrustRank

**Last Updated:** 2026-01-31
**Confidence:** High
**Status:** Implemented in `stemedb-storage` v0.1.0

## Summary

TrustRank is a per-agent reputation system that tracks accuracy and weights assertions in the Authority lens. This is the foundation of "The Hive" learning loop, enabling closed-loop learning where agent predictions are validated against reality.

**Key Facts:**
- Agent reputation scores range [0.0, 1.0]
- Default score for new agents: 0.5
- Accurate predictions increase reputation (+0.05)
- Inaccurate predictions decrease reputation (-0.1, higher penalty to discourage spam)
- Confidence half-life: Scores decay over time (default 30 days)
- Content-addressed by agent Ed25519 public key

**File Pointer:** `crates/stemedb-storage/src/trust_rank_store.rs`

## Data Model

```rust
pub struct TrustRank {
    pub agent_id: [u8; 32],          // Ed25519 public key
    pub score: f32,                   // Reputation [0.0, 1.0]
    pub last_updated: u64,            // Unix timestamp
    pub assertions_count: u64,        // Total assertions made
    pub accuracy_count: u64,          // Correct assertions
}
```

**Storage Layout:**
- Key: `TR:{agent_id}` (32-byte Ed25519 public key)
- Value: Serialized TrustRank (rkyv)

## Operations

### Get TrustRank

```rust
let trust = trust_store.get_trust_rank(&agent_id).await?;
```

Returns default TrustRank (score 0.5) for new agents.

### Update TrustRank

```rust
let new_score = trust_store.update_trust_rank(&agent_id, delta, timestamp).await?;
```

Adjusts score by delta, clamped to [0.0, 1.0].

### Record Outcome (Learning Loop)

```rust
let new_score = trust_store.record_outcome(&agent_id, was_accurate, timestamp).await?;
```

**Learning Rules:**
- `was_accurate = true`: score += 0.05, accuracy_count++
- `was_accurate = false`: score -= 0.1, assertions_count++ only
- Both: assertions_count++

### Apply Decay

```rust
let decayed_count = trust_store.decay_trust_ranks(current_timestamp, None).await?;
```

**Decay Formula:**
```
score = score * (0.5 ^ (elapsed_days / half_life_days))
```

Default half-life: 30 days. Custom half-life can be provided.

## The Hive Learning Loop

```
1. Agent submits assertion with confidence 0.8
   -> TrustRank lookup: 0.7 (experienced agent)
   -> Weighted score: 0.8 * 0.7 = 0.56

2. Reality assertion arrives (e.g., official data)
   -> Compare: Did the agent's prediction match?

3. Outcome recorded:
   -> If accurate: TrustRank 0.7 -> 0.75
   -> If inaccurate: TrustRank 0.7 -> 0.6

4. Future assertions from this agent weighted accordingly
```

## Integration with Authority Lens

The TrustAwareAuthorityLens uses TrustRank to weight assertions:

```rust
use stemedb_lens::TrustAwareAuthorityLens;

let lens = TrustAwareAuthorityLens::new(trust_store);
let resolution = lens.resolve_async(&candidates).await;

// Resolution selects assertion with highest:
// weighted_score = assertion.confidence * agent.trust_rank
```

**Example Scenario:**

| Agent | Assertion Confidence | TrustRank | Weighted Score | Winner? |
|-------|---------------------|-----------|----------------|---------|
| Novice | 0.95 | 0.2 | 0.19 | No |
| Expert | 0.8 | 0.7 | 0.56 | No |
| Master | 0.75 | 0.95 | 0.7125 | ✅ Yes |

The Master's assertion wins despite lower raw confidence because their reputation is highest.

## Decay Mechanics

TrustRank decays over time to reflect that past accuracy doesn't guarantee future accuracy.

**Half-Life Examples:**

| Initial Score | Time Elapsed | Final Score |
|--------------|--------------|-------------|
| 1.0 | 30 days | 0.5 |
| 1.0 | 60 days | 0.25 |
| 0.8 | 30 days | 0.4 |
| 0.5 | 30 days | 0.25 |

**Why Decay?**
- Agents may become less accurate over time (model drift, outdated knowledge)
- Prevents "tenured" agents from coasting on past reputation
- Forces continuous demonstration of accuracy

## Testing

Comprehensive test coverage in `trust_rank_store.rs`:

```rust
#[tokio::test]
async fn test_record_outcome_updates_score() {
    let trust_store = GenericTrustRankStore::new(store);
    let agent_id = [1u8; 32];

    // Record accurate outcome
    let score = trust_store.record_outcome(&agent_id, true, 1000).await?;
    assert!((score - 0.55).abs() < 0.001); // 0.5 + 0.05

    // Record inaccurate outcome
    let score = trust_store.record_outcome(&agent_id, false, 2000).await?;
    assert!((score - 0.45).abs() < 0.001); // 0.55 - 0.1

    let trust = trust_store.get_trust_rank(&agent_id).await?;
    assert_eq!(trust.assertions_count, 2);
    assert_eq!(trust.accuracy_count, 1);
    assert_eq!(trust.accuracy_rate(), 0.5);
}
```

## Future Enhancements

- **Domain-Specific TrustRank:** Track reputation per subject/predicate domain
- **Multi-Signature Aggregation:** Combine TrustRanks of all signers, not just primary
- **Adaptive Learning Rates:** Adjust delta based on agent's history
- **Trust Graph:** Factor in reputation of agents who vouch for this agent
- **Adversarial Detection:** Identify and penalize coordinated attacks

## Related Topics

- [Lens](../services/lens.md) - TrustAwareAuthorityLens integration
- [The Hive](../../vision.md) - Learning loop vision
- [Simulation](./simulation.md) - Testing TrustRank in controlled scenarios