stanford-ml-phd: EigenTrust plugin for the trust layer

Description

The pitch.

## Which piece and why

**Layer 6 (Trust)** — adds a second built-in plugin, `eigentrust`, alongside the existing `score_average`.

The default `score_average` plugin is the textbook naive baseline: every report counts equally and the reporter's identity is ignored. That's fine as scaffolding but it means the `reputation` scenario can't actually surface anything interesting about *who* is reporting *whom* — a Sybil clique can promote itself to the top in O(reports), so any protocol researcher comparing against `score_average` is fighting a strawman. As an ML/security researcher this is the layer where the bundled reference plugin most clearly limits what NEST can reveal.

## Core idea

`EigenTrust` (Kamvar, Schlosser, Garcia-Molina; WWW '03) — the canonical "trust as graph centrality" algorithm and a frequent baseline in the multi-agent / P2P-reputation literature.

- Maintain a sparse local-trust matrix `C[reporter][subject]` from `Evidence` reports (positive minus negative, then row-normalized).
- Compute the global trust vector as the principal left eigenvector of the teleport-smoothed matrix via sparse power iteration: `t ← (1 − α)·Cᵀ t + α·p`.
- `p` is a configurable pre-trusted seed distribution (defaults to uniform over observed agents); reporters with no usable local trust are treated as dangling and redistributed through `p`, mirroring the standard PageRank reformulation.
- Cached lazily: `report` marks dirty, `score` recomputes on demand — so many `score` queries between reports are essentially free.
- Deterministic under sorted agent ordering with a fixed iteration cap (64) and tolerance (1e-8). Same evidence sequence → bit-identical global-trust vector. NEST's "same seed → same trace" guarantee is preserved.

No new runtime dependencies (no NumPy); pure Python dict-of-dicts so cost scales with edges, not n².

## How to test

Unit + property tests (16, all passing):

```bash
uv run pytest packages/nest-plugins-reference/tests/test_eigentrust.py -v
```

Headline adversarial properties covered:

- `test_sybil_clique_cannot_promote_itself` — 10 Sybils circle-vouching 5× each cannot beat one honest agent with a single seed endorsement.
- `test_self_vouching_does_not_inflate` — agents reporting themselves do not climb above a seed-anchored peer.
- `test_distrusted_reporter_cannot_swing_against_seed` — 200 rogue negative reports + 200 rogue self-promotions still leave a seed-anchored target above the rogue.
- `test_eigentrust_separates_cheater_below_honest` — miniature of the bundled `reputation` scenario: cheater ends strictly below every honest agent.
- `test_same_evidence_sequence_yields_identical_vector` — determinism check (bit-equal floats across runs).

End-to-end swap against the `reputation` scenario:

```yaml
# scenarios/reputation.yaml
layers:
  trust: eigentrust   # was: score_average
```

```bash
uv run nest run scenarios/reputation.yaml
uv run python -c "from pathlib import Path; from nest_core.validators import validate_trace; \
  [print(('PASS' if r.passed else 'FAIL'), r.name) for r in validate_trace(Path('traces/reputation.jsonl'), 'reputation')]"
```

Full workspace suite (regression check): `uv run pytest packages/ -q` → **275 passed** (up from 259 with my 16 new tests).

Lint + types both clean: `uv run ruff check ...` and `uv run pyright ...` pass on the new files.

## Key assumptions

- α (teleport probability) defaults to 0.15, the PageRank canonical value; the paper recommends 0.1–0.2. Exposed as a constructor kwarg.
- Without an explicit `pre_trusted` set, `p` is uniform over agents that have appeared as a reporter or subject. With explicit seeds that haven't appeared yet, the algorithm falls back to uniform rather than concentrating mass on absent agents.
- Score is normalized by dividing by the max raw eigenvector entry, so the most-trusted agent gets ~1.0. This matches `score_average`'s [0, 1] scale for fair side-by-side comparisons.
- Unknown agents return the same neutral prior (0.5) as `score_average`, so baseline numbers don't shift on a plugin swap.
- `Trust.stake` is kept as interface-compatible passthrough; staking does not influence the eigenvector in this implementation (could be added later via weighting `p`).
- The `reputation` scenario's `ObserverAgent` currently keeps its own counter and does not call `trust.score()`, so the plugin's effect on validator output is via the trust-layer state, not the trace. A natural follow-up is to have the observer publish the global trust vector to the blackboard so validators can assert on rank-ordering.

## Persona

Stanford ML PhD interested in adversarial multi-agent RL, benchmark design, and reproducibility — looking for plugins that turn NEST scenarios into proper protocol stress tests rather than smoke tests.

## Future work

- **Time-weighted EigenTrust** — apply an exponential decay to old reports before computing C (Kamvar 2003 §6, also explored in BetaReputation [Jøsang & Ismail]).
- **Stake-weighted seeds** — fold `stake()` amounts into the seed distribution `p` so committed-stake agents anchor the system, giving NEST a free testbed for proof-of-stake reputation.
- **Validator extension** — add a `trust_ranking` property check that compares the trust-layer global vector against ground-truth honesty labels in the `reputation` scenario (e.g., Spearman rank correlation between EigenTrust score and the actual cheat probability). That would turn the validator into a real adversarial benchmark.
- **EigenTrust on the marketplace scenario** — the bundled marketplace doesn't currently exercise the trust layer; wiring buyer-side `trust.score()` lookups before accepting a seller would let researchers benchmark trust-driven partner selection.

https://claude.ai/code/session_01C5j2D4MgCkPgsjSCqBVpWW

---
_Generated by [Claude Code](https://claude.ai/code/session_01C5j2D4MgCkPgsjSCqBVpWW)_

## Summary by Sourcery

Add a new EigenTrust-based trust plugin alongside the existing score_average implementation and document how to use it for Sybil-resistant reputation scoring.

New Features:
- Introduce an EigenTrust trust plugin that computes transitive, Sybil-resistant global reputation scores from evidence reports.
- Expose the EigenTrust plugin as a built-in trust-layer option that can be selected by name in scenarios.

Enhancements:
- Extend trust-layer documentation to describe all bundled trust plugins and how to switch between them in scenarios.
- Update the main README to mention EigenTrust as an additional built-in trust plugin at the Trust layer.

Tests:
- Add a comprehensive EigenTrust test suite covering protocol contract behaviour, Sybil-resistance properties, seed handling, determinism, and convergence characteristics.