# What SuperWitness is

SuperWitness is observability and evaluation for agent fleets. Give us one run of work and we bring
three views together for you: what the agent did, how the products around it behaved, and whether
the result was any good.

Generic observability tools stop at a trace. We follow that trace to the run it belongs to, the
attempts that executed it, the agent configuration behind them, and the verdicts that judged it.
That is how “did this configuration get better?” becomes a question you can answer instead of a
hunch with a dashboard.

## Three questions, one run

| Question | Where the answer comes from | In the run document |
|---|---|---|
| **What did it do?** | The attempts that executed the run, each with its configuration fingerprint, and the spans they left | `attempts`, `trace` |
| **How did the products run?** | Log lines and errors that carry the run's id or one of its trace ids | `log_count`, `errors` |
| **Was it any good?** | Gate decisions read from SuperPipeline, and verdicts recorded in SuperWitness | `verdicts` |

The run document is what `GET /v1/runs/superpipeline/{board}/{run}` returns. It is assembled at
read time from every source, and it says which sources answered: a source that is down shows as
`unavailable` or `timeout`, and the numbers it would have supplied show as `unknown`, never as 0.
[Concepts](/concepts/) has the vocabulary.

## Telemetry and evidence are different things

SuperWitness handles two kinds of data and keeps them apart:

| | Telemetry | Verdicts |
|---|---|---|
| What | Traces, metrics, logs | Grader scores, offline eval results, calibration runs, configuration comparisons |
| Loss | Expected: sampled, short retention | Never |
| Where | Upstream engines | SuperWitness's own database |

Telemetry lives in VictoriaTraces and VictoriaLogs, sent there through the OpenTelemetry
Collector. SuperWitness only queries it. Verdicts live in SuperWitness's own Postgres, where they
are append-only: database triggers refuse to update, delete or truncate them, and a change of
mind is a new verdict that supersedes the old one.

A missing span is not missing evidence. When a run has no spans, its trace status is `none` and
the rest of the document still stands.

Evidence that belongs to another product, such as a work run, a gate decision or a transcript,
stays in that product. SuperWitness reads it through that product's API and never becomes its
owner.

## The rules the project keeps

1. **It is meant to stand alone.** The design rule is that no other SuperJackfruit product
   should be required, so that anyone's agents can send OTLP and record verdicts. This release
   is not there yet: it reads runs from SuperPipeline and attempts from AgentPod, and without
   them it runs only in fake mode (below).
2. **Nothing requires it.** Products send plain OTLP and never wait on SuperWitness.
3. **Upstream engines, unforked.** SuperWitness queries VictoriaTraces and VictoriaLogs, fed by
   the OpenTelemetry Collector, through their published query APIs only. It is designed to sit
   beside VictoriaMetrics and Perses the same way: upstream releases, run as released, never
   forked.
4. **Permissive licences only** in anything linked or shipped: MIT, Apache-2.0, BSD. No AGPL, so
   no Grafana, Loki, Tempo or Mimir, and no source-available licences (ELv2, BSL, FSL, SSPL).
   Bundled components are credited in the `NOTICE` file in every release.
5. **Agents first.** It is evaluation and observability for agent fleets, with product health
   underneath. It is not a general monitoring platform that also handles agents.

## What this release reads

Run documents in this release are for SuperPipeline runs, addressed as
`superpipeline:<board>/<run>`, with attempts read from the AgentPod hub. Start SuperWitness against
real sources and it asks you for both products' URLs and an AgentPod service credential. If you
want to explore without either one, use `SW_FAKE_SOURCES=1`; you will get one development run on
loopback and can inspect the shape before wiring the real sources. The
[install guide](/install/#try-it-without-the-other-products) shows both paths.
