# Lens

**Last Updated:** 2026-01-31
**Confidence:** High

## Summary

A Lens resolves conflicting assertions into a deterministic answer at read time. Multiple truths coexist; the Lens chooses which to return.

**Key Facts:**
- Stateless compute (no side effects)
- Deterministic (same input = same output)
- Fast (runs on every read, avoid allocations)
- Pluggable (implement `Lens` trait)

**File Pointer:** `crates/stemedb-lens/src/lib.rs` (planned)

## The Trait

```rust
pub trait Lens {
    fn resolve(&self, candidates: &[Assertion], context: &QueryContext) -> LensResult;
}
```

## Standard Lenses

| Lens | Strategy | Use Case |
|------|----------|----------|
| Recency | Latest timestamp wins | News, real-time |
| Consensus | Highest vote count | Democratic truth |
| Authority | Weighted by agent reputation | Expert truth |
| Skeptic | Returns variance/conflict | Finding controversy |
| EpochAware | Filters superseded epochs first | Paradigm-safe queries |
| Constraints | Returns `must_use`/`forbidden` predicates | Pre-flight checks |

## Lens::Constraints (Pre-Flight Check)

Special lens for agent safety. Returns rules, not facts.

```
GET /query?context=python_http&lens=constraints

-> Returns:
{
  "constraints": [
    { "must_use": "axios", "forbidden": "requests", "reason": "User correction" }
  ]
}
```

**Origin:** Solves the "Optimization Conflict" where agents forget corrections. Acts as a compiler error for agent intent.

See [agile-agent-team.md](../../use-cases/agile-agent-team.md#feature-6-persistent-learning-negative-constraints--the-gardener) for full explanation.

## Query Flow

1. Client: `GET(Subject="Tesla", Predicate="Revenue", Lens="Consensus")`
2. Index lookup: `SP:Tesla:Revenue` -> `[Hash1, Hash2, Hash3]`
3. Hydrate: Load assertions from hashes
4. Resolve: `ConsensusLens.resolve(assertions, context)`
5. Return: Single deterministic answer with confidence

## Related Topics

- [Assertion](./assertion.md)
- [stemedb-lens skill](../../.claude/skills/stemedb-lens/SKILL.md)